package smith:plugin@0.1.0; /// Structured child invocation; caller identity, grants, and generation are host-owned. interface composition { /// Resolve an exact qualified target under the running caller authority. invoke: func(target: string, arguments-json: string) -> result; } interface tooling { record tool-declaration { name: string, description: string, input-schema-json: string, } record file-read { path: string, offset: u64, limit: u64, max-bytes: u64, } record file-content { text: string, } record file-write { path: string, content: string, } record file-edit { path: string, old-text: string, new-text: string, } record directory-query { path: string, pattern: option, } record command-request { text: string, timeout-ms: u64, } /// Read a bounded file window inside the host-granted workspace root. read: func(request: file-read) -> result; /// Atomically publish a file inside the host-granted workspace root. write: func(request: file-write) -> result<_, string>; /// Replace exactly one matching range inside the host-granted workspace root. edit: func(request: file-edit) -> result<_, string>; /// List one directory level inside the host-granted workspace root. list-directory: func(request: directory-query) -> result, string>; /// Find matching descendants inside the host-granted workspace root. find: func(request: directory-query) -> result, string>; /// Search matching lines inside the host-granted workspace root. grep: func(request: directory-query) -> result, string>; /// Run a bounded command with the host-granted workspace as cwd. run-command: func(request: command-request) -> result; } interface net-scope { record header { name: string, value: string, } record request-options { timeout-ms: u64, response-bytes-max: u64, } record http-request { destination: string, method: string, headers: list
, body: list, options: request-options, } record http-response { status: u16, headers: list
, body: list, } /// Execute only against a host-authorized destination with explicit bounds. request: func(request: http-request) -> result; } interface secret-proxy { /// Opaque host-issued secret identity; its plaintext never crosses WIT. record secret-ref { id: string, } record credential-exchange { source: secret-ref, audience: string, scopes: list, } /// Declarative public-client policy, compared with explicit host authority. enum login-flow { dynamic-oidc, fixed-client-pkce-opaque, google-installed-pkce, } record login-policy { flow: login-flow, connection-id: string, token-origin: string, issuer: string, audience: string, initial-client: string, issued-prefix: string, authorization-path: string, token-path: string, agent-name: string, scopes: list, required-scopes: list, } /// Metadata-only profile handle; no token crosses this interface. record profile-ref { id: string, } /// Bounded authorization operation failures, never engine diagnostics or credentials. variant authorization-fault { capability, authority, cancelled, deadline-exceeded, network, exchange-uncertain, rejected, storage, } /// Host owns callback, presentation, entropy, crypto, HTTP, and atomic storage. authorize: func(policy: login-policy) -> result; /// End the selected renewable session and always clear local tokens; bool confirms remote revocation. end-session: func(profile: profile-ref) -> result; /// Renew the explicitly selected profile after durable provider dispatch admission. renew: func(profile: profile-ref, policy: login-policy) -> result; /// Ask the host to derive another opaque credential reference. exchange: func(request: credential-exchange) -> result; } interface log { /// Record one bounded diagnostic message for this invocation. write: func(level: string, message: string) -> result<_, string>; } interface provider { variant settings-provenance { built-in, user, trusted-project, explicit, } record provider-settings { include-usage: bool, /// Host-selected billing mode; codecs must not infer it from credentials. subscription: bool, provenance: settings-provenance, } record model-capabilities { output-tokens-max: u64, tool-use: bool, thinking: bool, } record catalog-model { id: string, capabilities: model-capabilities, } variant catalog-source { bundled, cache, models-dev, } record catalog-snapshot { generation: u64, source: catalog-source, models: list, } variant message-role { system, user, assistant, tool, } record tool-use { name: string, input-json: string, call-id: string, } record tool-result { call-id: string, name: string, output: string, } variant message-block { text(string), thinking(string), tool-use(tool-use), tool-result(tool-result), } record provider-message { role: message-role, blocks: list, } record provider-tool { name: string, description: string, input-schema-json: string, } /// Host-bound noncredential Google subscription context. record code-assist-context { project: string, user-prompt-id: string, } record provider-request { code-assist: option, messages: list, tools: list, output-tokens-max: option, } record request-template { url: string, authorization: string, body: string, } record usage { input-tokens: u64, output-tokens: u64, input-cache-hit-tokens: u64, input-cache-write-tokens: u64, } variant stop-reason { end-turn, tool-use, limit, abort, stop-sequence, refusal, content-filter, } variant stream-event { text(string), thinking(string), tool-use(tool-use), stop(tuple>), } record decode-step { state: list, events: list, } /// Declare codec-owned default settings during registration. declare-settings: func() -> provider-settings; /// Validate immutable effective codec configuration. validate-settings: func(settings: provider-settings) -> result; /// Purely map one provider-neutral request plus immutable host snapshots to a request template. build-request: func(model: string, request: provider-request, settings: provider-settings, catalog: catalog-snapshot) -> result; /// Decode one bounded raw response chunk with explicit host-owned codec state. decode-response: func(state: list, chunk: list, finished: bool) -> result; } interface registration { variant protocol-binding { openai-compatible, anthropic-messages, google-gemini, } record credential-source { id: string, } record provider-contribution { id: string, protocol: protocol-binding, credential-source-id: string, } record model-contribution { id: string, provider-id: string, } record registrations { credential-sources: list, providers: list, models: list, } /// Static declaration pass with no operational effects. declare: func() -> registrations; } interface plugin { use tooling.{tool-declaration}; /// Static declaration pass: runs at instantiation, before publication, /// and may not perform host effects. declare-tools: func() -> list; /// Invoke one declared tool by name; input and output are canonical JSON. invoke: func(name: string, input-json: string) -> result; } /// Optional major-versioned renewable module; only credential providers export it. interface credential-source-v1 { use secret-proxy.{profile-ref, secret-ref, authorization-fault}; resource credential-source { constructor(profile: profile-ref, fixture-issuer: option, connection-id: string); renew: func() -> result; } } /// Optional protocol-specific binding; absence leaves legacy protocol exports unchanged. interface protocol-openai-responses-v1 { /// Static major-versioned credential-source dependency, never an operational effect. credential-source: func() -> string; } world responses-world { include plugin-world; export protocol-openai-responses-v1; } world oauth-world { include plugin-world; export credential-source-v1; } world plugin-world { import composition; import tooling; import net-scope; import secret-proxy; import log; export plugin; export provider; export registration; } // SMH-SPEC-PLUG0001: optional actionable run boundaries. interface lifecycle { use provider.{stop-reason}; enum boundary { turn-complete, pre-settlement, settled } record event { root-entry-id: tuple, boundary: boundary, round-index: u32, last-stop: stop-reason, continuation-eligible: bool, } record handler-declaration { name: string, boundary: boundary, required-decision: bool } variant replacement { text(string), assistant-text(string), tool-result-output(tuple, string>), } record context-edit { target: tuple, replacement: option } enum availability { advertised, hidden, disabled } record tool-policy-change { name: string, availability: availability } variant action { cancel, ensure-continuation, edit-context(list), set-model(string), set-provider(string), set-prompt(string), set-tool-policy(list), include-usage(bool), } declare-handlers: func() -> list; handle: func(name: string, event: event) -> result, string>; } world lifecycle-world { include plugin-world; export lifecycle; }