@finalai/agent-provider 0.1.2 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/HOSTING.md +234 -0
- package/dist/modules/channel.d.mts +4 -0
- package/dist/modules/channel.mjs.map +2 -2
- package/dist/modules/dynamic.d.mts +8 -0
- package/dist/modules/dynamic.mjs +3 -1
- package/dist/modules/dynamic.mjs.map +2 -2
- package/dist/modules/harness.d.mts +3 -0
- package/dist/modules/harness.mjs +5 -1
- package/dist/modules/harness.mjs.map +2 -2
- package/dist/modules/hosted-bindings.d.mts +15 -0
- package/dist/modules/hosted-bindings.mjs +21 -0
- package/dist/modules/hosted-bindings.mjs.map +7 -0
- package/dist/modules/index.d.mts +3 -0
- package/dist/modules/index.mjs +3 -0
- package/dist/modules/index.mjs.map +2 -2
- package/dist/modules/manifest.d.mts +143 -6
- package/dist/modules/manifest.mjs +33 -5
- package/dist/modules/manifest.mjs.map +3 -3
- package/dist/modules/sandbox/types.d.mts +5 -0
- package/dist/modules/sandbox/types.mjs.map +2 -2
- package/dist/modules/tool-annotations.d.mts +7 -0
- package/dist/modules/tool-annotations.mjs +10 -0
- package/dist/modules/tool-annotations.mjs.map +7 -0
- package/dist/modules/tool-patterns.d.mts +11 -0
- package/dist/modules/tool-patterns.mjs +65 -0
- package/dist/modules/tool-patterns.mjs.map +7 -0
- package/package.json +4 -3
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"version": 3,
|
|
3
3
|
"sources": ["../../../../../src/sandbox/types.ts"],
|
|
4
|
-
"sourcesContent": ["import type {\n ProcessInspectionRequestIface,\n ProcessInspectionResultIface,\n} from '@finalai/agent-protocol/process-inspection';\nimport type { JsonValue } from \"../json.mjs\";\nimport type { ToolDescriptorIface } from \"../manifest.mjs\";\nimport type { SandboxEditorRequestIface, SandboxEditorResultIface } from \"./editor.mjs\";\nimport { awaitableOpenRequest, type AwaitableSandboxOpenRequestIface } from \"./open-scope.mjs\";\nimport type { SandboxSnapshotRequestIface, SandboxSnapshotResponseIface } from \"./snapshots.mjs\";\n\n// Sandbox providers and consumers share the streaming session contract.\n\nexport interface AbortableIface {\n abortSignal?: AbortSignal;\n}\n\nexport interface SandboxProcessOptionsIface extends AbortableIface {\n command: string;\n args?: string[];\n cwd?: string;\n env?: Record<string, string>;\n // Run through the sandbox's login shell (`bash -lc`) instead of exec'ing.\n shell?: boolean;\n stdin?: ReadableStream<Uint8Array> | string;\n timeoutMs?: number;\n}\n\nexport interface SandboxProcessIface {\n readonly pid: string | null;\n readonly stdout: ReadableStream<Uint8Array>;\n readonly stderr: ReadableStream<Uint8Array>;\n // Writes to the process's stdin; closes stdin when `end` is true.\n write(data: Uint8Array | string, options?: { end?: boolean }): Promise<void>;\n wait(): Promise<{ exitCode: number }>;\n kill(signal?: string): Promise<void>;\n}\n\nexport interface SandboxRunResultIface {\n exitCode: number;\n stdout: string;\n stderr: string;\n}\n\nexport enum SandboxEntryType {\n File = 'file',\n Directory = 'directory',\n Symlink = 'symlink',\n Other = 'other',\n}\n\nexport interface StatIface {\n path: string;\n type: SandboxEntryType;\n size: number;\n modifiedAt: string | null;\n mode: number | null;\n}\n\nexport interface DirEntryIface {\n name: string;\n path: string;\n type: SandboxEntryType;\n size: number | null;\n}\n\nexport interface ConfinedSandboxFilesIface {\n readFile(\n options: { path: string; root: string } & AbortableIface,\n ): Promise<ReadableStream<Uint8Array> | null>;\n stat(options: { path: string; root: string } & AbortableIface): Promise<StatIface | null>;\n readDir(\n options: { path: string; root: string } & AbortableIface,\n ): Promise<DirEntryIface[] | null>;\n}\n\nexport interface SandboxSessionIface {\n readonly description: string;\n readonly confinedFileReader?: ConfinedSandboxFilesIface;\n // On the RPC surface, root confines viewer reads to this directory, rejects\n // symlink ancestors and requires Python 3 in the sandbox (confinedFiles feature).\n readFile(\n options: { path: string; root?: string } & AbortableIface,\n ): Promise<ReadableStream<Uint8Array> | null>;\n readBinaryFile(options: { path: string } & AbortableIface): Promise<Uint8Array | null>;\n readTextFile(\n options: {\n path: string;\n encoding?: string;\n startLine?: number;\n endLine?: number;\n } & AbortableIface,\n ): Promise<string | null>;\n writeFile(\n options: { path: string; content: ReadableStream<Uint8Array> } & AbortableIface,\n ): Promise<void>;\n writeBinaryFile(options: { path: string; content: Uint8Array } & AbortableIface): Promise<void>;\n writeTextFile(\n options: { path: string; content: string; encoding?: string } & AbortableIface,\n ): Promise<void>;\n spawn(options: SandboxProcessOptionsIface): Promise<SandboxProcessIface>;\n run(options: SandboxProcessOptionsIface): Promise<SandboxRunResultIface>;\n stat(options: { path: string; root?: string } & AbortableIface): Promise<StatIface | null>;\n readDir(options: { path: string; root?: string } & AbortableIface): Promise<DirEntryIface[]>;\n resolvePath(path: string): string;\n removePath(\n options: { path: string; recursive?: boolean; force?: boolean } & AbortableIface,\n ): Promise<void>;\n}\n\nexport enum NetworkPolicy {\n AllowAll = 'allow-all',\n DenyAll = 'deny-all',\n Allowlist = 'allowlist',\n}\n\nexport interface NetworkPolicyIface {\n mode: NetworkPolicy;\n allow?: string[];\n}\n\nexport enum PortProtocol {\n Http = 'http',\n Https = 'https',\n Ws = 'ws',\n}\n\n// An MCP transport the sandbox serves for an optional capability: an HTTP MCP\n// endpoint the harness (or the session service) can dial.\nexport interface McpEndpointIface {\n name: string;\n url: string;\n headers: Record<string, string>;\n}\n\n// A JSON-RPC message channel to an MCP server the sandbox hosts, for backends\n// whose API reaches it some other way than HTTP MCP (a byte pipe, a socket).\n// Messages are JSON-RPC objects, in order.\nexport interface McpChannelIface {\n send(message: JsonValue, options?: AbortableIface): Promise<void>;\n // The messages that arrived since the last call; [] when none did.\n receive(options?: AbortableIface): Promise<JsonValue[]>;\n close(): Promise<void>;\n}\n\n// An MCP server the sandbox hosts, opened in process by whoever runs the handle.\n// It cannot cross the handle RPC wire.\nexport interface McpChannelEndpointIface {\n name: string;\n connect(options?: AbortableIface): Promise<McpChannelIface>;\n}\n\nexport type SandboxMcpEndpoint = McpEndpointIface | McpChannelEndpointIface;\n\n// The tools of a sandbox's hosted MCP servers, as far as they are known without\n// starting it. Null: unknown until the sandbox is attached and asked.\nexport interface SandboxMcpCatalogIface {\n computerUse: ToolDescriptorIface[] | null;\n // Local MCP server name \u2192 its tools.\n localMcp: Record<string, ToolDescriptorIface[]> | null;\n}\n\nexport const isMcpChannelEndpoint = (\n endpoint: SandboxMcpEndpoint,\n): endpoint is McpChannelEndpointIface => 'connect' in endpoint;\n\nexport interface ScreenOptionsIface {\n // View-only by default; explicit input control requires execute access.\n viewOnly?: boolean;\n}\n\nexport interface ScreenSessionIface {\n // A short-lived viewer grant; providers enforce the requested input access.\n url: string;\n token: string;\n expiresAt: string;\n}\n\nexport interface NetworkSandboxSessionIface extends SandboxSessionIface {\n readonly id: string;\n readonly defaultWorkingDirectory: string;\n readonly ports: readonly number[];\n getPortEndpoint(options: {\n port: number;\n protocol?: PortProtocol;\n }): Promise<{ url: string; headers?: Record<string, string> }>;\n getPortUrl(options: { port: number; protocol?: PortProtocol }): Promise<string>;\n stop(): Promise<void>;\n destroy(): Promise<void>;\n setNetworkPolicy?(policy: NetworkPolicyIface): Promise<void>;\n computerUse?(): Promise<SandboxMcpEndpoint>;\n screen?(options?: ScreenOptionsIface): Promise<ScreenSessionIface>;\n localMcp?(): Promise<SandboxMcpEndpoint[]>;\n}\n\n// Capabilities a started sandbox advertises (and the handle RPC exposes).\nexport enum SandboxCapability {\n Files = 'files',\n Process = 'process',\n Ports = 'ports',\n NetworkPolicy = 'networkPolicy',\n ComputerUse = 'computerUse',\n Screen = 'screen',\n LocalMcp = 'localMcp',\n Browser = 'browser',\n}\n\nexport interface SandboxProviderHandleIface<S extends SandboxSessionIface> {\n readonly sandbox: S;\n onSandboxStop(): Promise<void>;\n onSandboxDelete(options?: { reason?: string }): Promise<void>;\n onRuntimeShutdown(): Promise<void>;\n}\n\n// A saved computer setup guide version: Build's versioned build-\n// and start-time inputs for a sandbox, as the session service serves them.\nexport interface SandboxGuideVersionIface {\n guideId: string;\n versionId: string;\n slug: string;\n title: string;\n number: number;\n image: string;\n // `.final/sandbox-template.yaml` v2 as JSON.\n templateConfig: JsonValue;\n // The start-time parameters this version defaults to.\n defaultParameters: JsonValue;\n instructionsMarkdown: string | null;\n // A ready build from the guide's provider, reusable independently of workspace seeds.\n preparedArtifact?: { providerRef: string; key: string; artifact: JsonValue };\n}\n\n// The organization's computer setup guides, read through the session service.\n// Every provider gets the same reader; a provider whose\n// environments name no guide never calls it.\nexport interface SandboxGuidesIface {\n get(args: { ref: string; version: number | 'latest' }): Promise<SandboxGuideVersionIface | null>;\n // The organization's default guide; null when it has none.\n default(): Promise<SandboxGuideVersionIface | null>;\n}\n\n// Where to clone a repository from, with a short-lived read credential that\n// must reach only the clone process (never a repository's git config).\nexport interface SandboxRepositoryCloneSourceIface {\n url: string;\n // Checked out after the clone; null keeps the default branch.\n ref: string | null;\n // An HTTP Authorization header value for the clone, or null.\n authorization: string | null;\n}\n\n// Repository credentials for the repositories an environment names (a Code\n// Storage id, a GitHub owner/name), resolved by the session service for the\n// session's organization only. Null: not a repository it can resolve.\nexport interface SandboxRepositoriesIface {\n cloneSource(args: {\n repository: string;\n ref: string | null;\n }): Promise<SandboxRepositoryCloneSourceIface | null>;\n}\n\n// Reads a named organization variable (managed in Build) for the session's\n// organization. Values are injected into the sandbox only, never stored in a\n// manifest, a state or the log.\nexport interface SandboxVariablesIface {\n get(name: string): Promise<string | null>;\n}\n\nexport const noSandboxGuides: SandboxGuidesIface = {\n get: async () => null,\n default: async () => null,\n};\n\nexport const noSandboxRepositories: SandboxRepositoriesIface = {\n cloneSource: async () => null,\n};\n\nexport const noSandboxVariables: SandboxVariablesIface = { get: async () => null };\n\n// The user a session acts for: the author of its running turn, else its owner,\n// else the user whose Home its conversation is. A call a person makes through\n// the platform's sandbox viewer acts for that person instead. Null when it acts\n// for no user (a turn nobody prompted in a shared conversation) and outside any\n// session (a guide build). Read on each call, because it changes between turns\n// and between callers.\nexport interface SandboxActingUserIface {\n current(): Promise<string | null>;\n}\n\nexport const noSandboxActingUser: SandboxActingUserIface = { current: async () => null };\n\n// What an environment's pre-start reads (capabilities, mcpCatalog) are given.\nexport interface SandboxOfferContextIface {\n organizationId: string;\n actingUser: SandboxActingUserIface;\n}\n\n// What an environment's hooks are given before anything starts.\nexport interface SandboxEnvironmentContextIface {\n organizationId: string;\n guides: SandboxGuidesIface;\n}\n\n// Scoped by the host to this organization and provider. Providers can retain\n// reusable intermediate artifacts independently of a revision's seed files.\nexport interface SandboxArtifactsIface {\n get(key: string): Promise<JsonValue | null>;\n put(key: string, artifact: JsonValue): Promise<void>;\n}\n\nexport interface SandboxPreparationSourceIface {\n sourceRevision: string;\n read(): Promise<{ files: Record<string, string>; resources: Record<string, JsonValue> }>;\n}\n\nexport interface SandboxPrepareContextIface {\n // A host-persisted resource source; artifacts may retain its identity instead of seed contents.\n preparation?: SandboxPreparationSourceIface;\n artifacts?: SandboxArtifactsIface;\n // Agent revisions supply workspace-relative seeds; setup-guide builds supply\n // guide.json and optional instructions.md. Resources name workspace, skills or guide.\n // Model instructions remain harness config.\n files: Record<string, string>;\n resources: Record<string, JsonValue>;\n sourceRevision: string;\n storagePath: string;\n organizationId: string;\n // The guide inputs (build-time) an environment names, resolved by the platform.\n guides: SandboxGuidesIface;\n // Who the session the artifact is prepared for acts for, for environments that\n // name a backend resource relative to that user; the key must then name it.\n actingUser: SandboxActingUserIface;\n log?: (message: string) => void;\n}\n\nexport interface SandboxStartContextIface {\n /** Passive recovery only: never wake, create, seed, or restart backend services. */\n passive?: boolean;\n preparation?: SandboxPreparationSourceIface;\n session: {\n id: string;\n organizationId: string;\n conversationId: string | null;\n definitionId: string;\n bindingId: string;\n target: string;\n };\n storagePath: string;\n // Start-time inputs: guides, the variables to inject, repository credentials.\n guides: SandboxGuidesIface;\n variables: SandboxVariablesIface;\n repositories: SandboxRepositoriesIface;\n actingUser: SandboxActingUserIface;\n}\n\nexport enum SandboxSessionEndReason {\n Completed = 'completed',\n Expired = 'expired',\n Failed = 'failed',\n}\n\n// How long an environment's sandbox outlives a session: `session`\n// keeps it for the session's life; `conversation` gives every session in the\n// conversation one shared sandbox per target, surviving session resets;\n// `ephemeral` discards it when released.\nexport enum SandboxWorkspace {\n Session = 'session',\n Conversation = 'conversation',\n Ephemeral = 'ephemeral',\n}\n\nexport interface SandboxProviderImplementationIface<\n OpenOptions,\n Artifact extends JsonValue,\n State extends JsonValue,\n S extends NetworkSandboxSessionIface,\n> {\n // The workspace this environment declares, read before anything starts so the\n // session service knows which sessions share a binding. Absent or null: session.\n workspace?(ctx: SandboxEnvironmentContextIface): Promise<SandboxWorkspace | null>;\n // The capabilities this environment's sandboxes offer, read before anything\n // starts through the backend's own API. Absent or null: unknown\n // until started; local MCP is then not projected.\n capabilities?(ctx: SandboxOfferContextIface): Promise<SandboxCapability[] | null>;\n // The hosted MCP servers' tool catalogs the backend can give without starting\n // a sandbox (from its own records), so the MCP projection lists them from the\n // first `tools/list`. The projection checks a server's catalog against the\n // live server when a call first opens that server (servers a session never\n // uses stay closed) and announces a change with\n // `notifications/tools/list_changed`.\n //\n // Trade-off: a catalog left unknown (absent hook, null, or a null field) can\n // only be learned from the live sandbox, so the first `tools/list` that finds\n // it unknown starts the sandbox in the background, at session start rather\n // than on the first tool call. Otherwise those tools would never be listed,\n // and nothing would ever call them. Providers that can give the catalog keep\n // attach lazy.\n mcpCatalog?(ctx: SandboxOfferContextIface): Promise<SandboxMcpCatalogIface | null>;\n // Reads committed files without starting/resuming a sandbox. Null means the backend\n // is live or offers no snapshot. An unavailable sleeping snapshot must throw,\n // never fall through to a read that wakes it. Pin subsequent ranges by snapshotId.\n readSnapshot?(\n ctx: SandboxOfferContextIface,\n state: State,\n request: SandboxSnapshotRequestIface,\n ): Promise<SandboxSnapshotResponseIface | null>;\n // Inspect retained backend processes without opening, resuming or extending a sandbox.\n // Stop requires execute access; the provider also enforces backend ownership.\n processes?(\n ctx: SandboxOfferContextIface & { bindingId: string },\n state: State,\n request: ProcessInspectionRequestIface,\n ): Promise<ProcessInspectionResultIface>;\n // Browser editor for this provider's existing workspace. The host checks write\n // authorization; this hook never creates or wakes a backend. Credentials stay\n // in the authentication form, never the editor URL or stored provider state.\n editor?(\n ctx: SandboxOfferContextIface,\n state: State,\n request: SandboxEditorRequestIface,\n ): Promise<SandboxEditorResultIface>;\n // Content-addressed by `artifactKey`; the session service caches artifacts in\n // agent.sandbox_artifacts and calls prepare only on a miss.\n artifactKey(ctx: SandboxPrepareContextIface): Promise<string>;\n prepare(ctx: SandboxPrepareContextIface): Promise<Artifact>;\n // `region`: where the backend placed the sandbox (its own region name), so the\n // session service can place the harness near it; null when unknown.\n start(\n ctx: SandboxStartContextIface,\n options: OpenOptions | undefined,\n artifact: Artifact,\n ): Promise<{ handle: SandboxProviderHandleIface<S>; state: State; region?: string | null }>;\n resume(\n ctx: SandboxStartContextIface,\n artifact: Artifact,\n state: State,\n ): Promise<SandboxProviderHandleIface<S>>;\n // Reconnect to an already running backend after host restart for a read-only viewer.\n // Absent: viewers can use a retained live handle but cannot trigger resume.\n resumePassive?(\n ctx: SandboxStartContextIface,\n artifact: Artifact,\n state: State,\n ): Promise<SandboxProviderHandleIface<S>>;\n // Park: pause or stop the sandbox, returning the state resume needs.\n park?(ctx: SandboxStartContextIface, artifact: Artifact, state: State): Promise<State>;\n onSessionEnd?(\n ctx: SandboxStartContextIface,\n artifact: Artifact,\n state: State,\n options: { reason: SandboxSessionEndReason },\n ): Promise<void>;\n}\n\nexport interface SandboxProviderDefinitionIface<\n EnvOptions,\n OpenOptions,\n Artifact extends JsonValue,\n State extends JsonValue,\n S extends NetworkSandboxSessionIface,\n> {\n name: string;\n // The version of `State`'s shape. The session service records it with each\n // binding and refuses to resume a state written under another version (the\n // next call starts the sandbox again instead).\n stateProtocolVersion?: number;\n environment(\n options?: EnvOptions,\n ): SandboxProviderImplementationIface<OpenOptions, Artifact, State, S>;\n}\n\n// A defined provider: the definition plus authoring sugar. `environment(opts)`\n// returns an environment whose `.open(openOptions)` records a sandbox binding\n// target when authored, and is what the session service drives at run time.\nexport interface SandboxProviderIface<\n EnvOptions,\n OpenOptions,\n Artifact extends JsonValue,\n State extends JsonValue,\n S extends NetworkSandboxSessionIface,\n> {\n readonly definition: SandboxProviderDefinitionIface<EnvOptions, OpenOptions, Artifact, State, S>;\n readonly name: string;\n environment(options?: EnvOptions): AwaitableSandboxEnvironmentIface<EnvOptions, OpenOptions>;\n}\n\nexport interface SandboxEnvironmentIface<EnvOptions, OpenOptions> {\n readonly providerName: string;\n readonly options: EnvOptions | undefined;\n // Provider-authored notices shown by the compiler and Build before publication.\n readonly authoringWarnings?: readonly string[];\n // Authoring: records the open options (access, ...) for this target.\n open(options?: OpenOptions): SandboxOpenRequestIface<EnvOptions, OpenOptions>;\n}\n\n// An environment whose open request a sandbox.ts selector can await to get\n// the live session (open-scope.ts); what defineSandboxProvider and the\n// installed helpers return.\nexport interface AwaitableSandboxEnvironmentIface<\n EnvOptions,\n OpenOptions,\n> extends SandboxEnvironmentIface<EnvOptions, OpenOptions> {\n open(options?: OpenOptions): AwaitableSandboxOpenRequestIface<EnvOptions, OpenOptions>;\n}\n\nexport interface SandboxOpenRequestIface<EnvOptions, OpenOptions> {\n readonly providerName: string;\n readonly environmentOptions: EnvOptions | undefined;\n readonly openOptions: OpenOptions | undefined;\n readonly authoringWarnings?: readonly string[];\n}\n\nexport const defineSandboxProvider = <\n EnvOptions,\n OpenOptions,\n Artifact extends JsonValue,\n State extends JsonValue,\n S extends NetworkSandboxSessionIface,\n>(\n definition: SandboxProviderDefinitionIface<EnvOptions, OpenOptions, Artifact, State, S>,\n): SandboxProviderIface<EnvOptions, OpenOptions, Artifact, State, S> => ({\n definition,\n name: definition.name,\n environment: (options) => ({\n providerName: definition.name,\n options,\n open: (openOptions) =>\n awaitableOpenRequest({\n providerName: definition.name,\n environmentOptions: options,\n openOptions,\n }),\n }),\n});\n\n// Erased form the session service stores in its provider registry.\nexport type AnySandboxProviderIface = SandboxProviderIface<\n JsonValue,\n JsonValue,\n JsonValue,\n JsonValue,\n NetworkSandboxSessionIface\n>;\n\n// Events emitted through a sandbox provider's process lifecycle.\nexport enum SandboxEventKind {\n ProcessExited = 'process_exited',\n}\n"],
|
|
5
|
-
"mappings": "
|
|
4
|
+
"sourcesContent": ["import type { HostedBindingsIface } from \"../hosted-bindings.mjs\";\nimport type {\n ProcessInspectionRequestIface,\n ProcessInspectionResultIface,\n} from '@finalai/agent-protocol/process-inspection';\nimport type { JsonValue } from \"../json.mjs\";\nimport type { ToolDescriptorIface } from \"../manifest.mjs\";\nimport type { SandboxEditorRequestIface, SandboxEditorResultIface } from \"./editor.mjs\";\nimport { awaitableOpenRequest, type AwaitableSandboxOpenRequestIface } from \"./open-scope.mjs\";\nimport type { SandboxSnapshotRequestIface, SandboxSnapshotResponseIface } from \"./snapshots.mjs\";\n\n// Sandbox providers and consumers share the streaming session contract.\n\nexport interface AbortableIface {\n abortSignal?: AbortSignal;\n}\n\nexport interface SandboxProcessOptionsIface extends AbortableIface {\n command: string;\n args?: string[];\n cwd?: string;\n env?: Record<string, string>;\n // Run through the sandbox's login shell (`bash -lc`) instead of exec'ing.\n shell?: boolean;\n stdin?: ReadableStream<Uint8Array> | string;\n timeoutMs?: number;\n}\n\nexport interface SandboxProcessIface {\n readonly pid: string | null;\n readonly stdout: ReadableStream<Uint8Array>;\n readonly stderr: ReadableStream<Uint8Array>;\n // Writes to the process's stdin; closes stdin when `end` is true.\n write(data: Uint8Array | string, options?: { end?: boolean }): Promise<void>;\n wait(): Promise<{ exitCode: number }>;\n kill(signal?: string): Promise<void>;\n}\n\nexport interface SandboxRunResultIface {\n exitCode: number;\n stdout: string;\n stderr: string;\n}\n\nexport enum SandboxEntryType {\n File = 'file',\n Directory = 'directory',\n Symlink = 'symlink',\n Other = 'other',\n}\n\nexport interface StatIface {\n path: string;\n type: SandboxEntryType;\n size: number;\n modifiedAt: string | null;\n mode: number | null;\n}\n\nexport interface DirEntryIface {\n name: string;\n path: string;\n type: SandboxEntryType;\n size: number | null;\n}\n\nexport interface ConfinedSandboxFilesIface {\n readFile(\n options: { path: string; root: string } & AbortableIface,\n ): Promise<ReadableStream<Uint8Array> | null>;\n stat(options: { path: string; root: string } & AbortableIface): Promise<StatIface | null>;\n readDir(\n options: { path: string; root: string } & AbortableIface,\n ): Promise<DirEntryIface[] | null>;\n}\n\nexport interface SandboxSessionIface {\n readonly description: string;\n readonly confinedFileReader?: ConfinedSandboxFilesIface;\n // On the RPC surface, root confines viewer reads to this directory, rejects\n // symlink ancestors and requires Python 3 in the sandbox (confinedFiles feature).\n readFile(\n options: { path: string; root?: string } & AbortableIface,\n ): Promise<ReadableStream<Uint8Array> | null>;\n readBinaryFile(options: { path: string } & AbortableIface): Promise<Uint8Array | null>;\n readTextFile(\n options: {\n path: string;\n encoding?: string;\n startLine?: number;\n endLine?: number;\n } & AbortableIface,\n ): Promise<string | null>;\n writeFile(\n options: { path: string; content: ReadableStream<Uint8Array> } & AbortableIface,\n ): Promise<void>;\n writeBinaryFile(options: { path: string; content: Uint8Array } & AbortableIface): Promise<void>;\n writeTextFile(\n options: { path: string; content: string; encoding?: string } & AbortableIface,\n ): Promise<void>;\n spawn(options: SandboxProcessOptionsIface): Promise<SandboxProcessIface>;\n run(options: SandboxProcessOptionsIface): Promise<SandboxRunResultIface>;\n stat(options: { path: string; root?: string } & AbortableIface): Promise<StatIface | null>;\n readDir(options: { path: string; root?: string } & AbortableIface): Promise<DirEntryIface[]>;\n resolvePath(path: string): string;\n removePath(\n options: { path: string; recursive?: boolean; force?: boolean } & AbortableIface,\n ): Promise<void>;\n}\n\nexport enum NetworkPolicy {\n AllowAll = 'allow-all',\n DenyAll = 'deny-all',\n Allowlist = 'allowlist',\n}\n\nexport interface NetworkPolicyIface {\n mode: NetworkPolicy;\n allow?: string[];\n}\n\nexport enum PortProtocol {\n Http = 'http',\n Https = 'https',\n Ws = 'ws',\n}\n\n// An MCP transport the sandbox serves for an optional capability: an HTTP MCP\n// endpoint the harness (or the session service) can dial.\nexport interface McpEndpointIface {\n name: string;\n url: string;\n headers: Record<string, string>;\n}\n\n// A JSON-RPC message channel to an MCP server the sandbox hosts, for backends\n// whose API reaches it some other way than HTTP MCP (a byte pipe, a socket).\n// Messages are JSON-RPC objects, in order.\nexport interface McpChannelIface {\n send(message: JsonValue, options?: AbortableIface): Promise<void>;\n // The messages that arrived since the last call; [] when none did.\n receive(options?: AbortableIface): Promise<JsonValue[]>;\n close(): Promise<void>;\n}\n\n// An MCP server the sandbox hosts, opened in process by whoever runs the handle.\n// It cannot cross the handle RPC wire.\nexport interface McpChannelEndpointIface {\n name: string;\n connect(options?: AbortableIface): Promise<McpChannelIface>;\n}\n\nexport type SandboxMcpEndpoint = McpEndpointIface | McpChannelEndpointIface;\n\n// The tools of a sandbox's hosted MCP servers, as far as they are known without\n// starting it. Null: unknown until the sandbox is attached and asked.\nexport interface SandboxMcpCatalogIface {\n computerUse: ToolDescriptorIface[] | null;\n // Local MCP server name \u2192 its tools.\n localMcp: Record<string, ToolDescriptorIface[]> | null;\n}\n\nexport const isMcpChannelEndpoint = (\n endpoint: SandboxMcpEndpoint,\n): endpoint is McpChannelEndpointIface => 'connect' in endpoint;\n\nexport interface ScreenOptionsIface {\n // View-only by default; explicit input control requires execute access.\n viewOnly?: boolean;\n}\n\nexport interface ScreenSessionIface {\n // A short-lived viewer grant; providers enforce the requested input access.\n url: string;\n token: string;\n expiresAt: string;\n}\n\nexport interface NetworkSandboxSessionIface extends SandboxSessionIface {\n readonly id: string;\n readonly defaultWorkingDirectory: string;\n readonly ports: readonly number[];\n getPortEndpoint(options: {\n port: number;\n protocol?: PortProtocol;\n }): Promise<{ url: string; headers?: Record<string, string> }>;\n getPortUrl(options: { port: number; protocol?: PortProtocol }): Promise<string>;\n stop(): Promise<void>;\n destroy(): Promise<void>;\n setNetworkPolicy?(policy: NetworkPolicyIface): Promise<void>;\n computerUse?(): Promise<SandboxMcpEndpoint>;\n screen?(options?: ScreenOptionsIface): Promise<ScreenSessionIface>;\n localMcp?(): Promise<SandboxMcpEndpoint[]>;\n}\n\n// Capabilities a started sandbox advertises (and the handle RPC exposes).\nexport enum SandboxCapability {\n Files = 'files',\n Process = 'process',\n Ports = 'ports',\n NetworkPolicy = 'networkPolicy',\n ComputerUse = 'computerUse',\n Screen = 'screen',\n LocalMcp = 'localMcp',\n Browser = 'browser',\n}\n\nexport interface SandboxProviderHandleIface<S extends SandboxSessionIface> {\n readonly sandbox: S;\n onSandboxStop(): Promise<void>;\n onSandboxDelete(options?: { reason?: string }): Promise<void>;\n onRuntimeShutdown(): Promise<void>;\n}\n\n// A saved computer setup guide version: Build's versioned build-\n// and start-time inputs for a sandbox, as the session service serves them.\nexport interface SandboxGuideVersionIface {\n guideId: string;\n versionId: string;\n slug: string;\n title: string;\n number: number;\n image: string;\n // `.final/sandbox-template.yaml` v2 as JSON.\n templateConfig: JsonValue;\n // The start-time parameters this version defaults to.\n defaultParameters: JsonValue;\n instructionsMarkdown: string | null;\n // A ready build from the guide's provider, reusable independently of workspace seeds.\n preparedArtifact?: { providerRef: string; key: string; artifact: JsonValue };\n}\n\n// The organization's computer setup guides, read through the session service.\n// Every provider gets the same reader; a provider whose\n// environments name no guide never calls it.\nexport interface SandboxGuidesIface {\n get(args: { ref: string; version: number | 'latest' }): Promise<SandboxGuideVersionIface | null>;\n // The organization's default guide; null when it has none.\n default(): Promise<SandboxGuideVersionIface | null>;\n}\n\n// Where to clone a repository from, with a short-lived read credential that\n// must reach only the clone process (never a repository's git config).\nexport interface SandboxRepositoryCloneSourceIface {\n url: string;\n // Checked out after the clone; null keeps the default branch.\n ref: string | null;\n // An HTTP Authorization header value for the clone, or null.\n authorization: string | null;\n}\n\n// Repository credentials for the repositories an environment names (a Code\n// Storage id, a GitHub owner/name), resolved by the session service for the\n// session's organization only. Null: not a repository it can resolve.\nexport interface SandboxRepositoriesIface {\n cloneSource(args: {\n repository: string;\n ref: string | null;\n }): Promise<SandboxRepositoryCloneSourceIface | null>;\n}\n\n// Reads a named organization variable (managed in Build) for the session's\n// organization. Values are injected into the sandbox only, never stored in a\n// manifest, a state or the log.\nexport interface SandboxVariablesIface {\n get(name: string): Promise<string | null>;\n}\n\nexport const noSandboxGuides: SandboxGuidesIface = {\n get: async () => null,\n default: async () => null,\n};\n\nexport const noSandboxRepositories: SandboxRepositoriesIface = {\n cloneSource: async () => null,\n};\n\nexport const noSandboxVariables: SandboxVariablesIface = { get: async () => null };\n\n// The user a session acts for: the author of its running turn, else its owner,\n// else the user whose Home its conversation is. A call a person makes through\n// the platform's sandbox viewer acts for that person instead. Null when it acts\n// for no user (a turn nobody prompted in a shared conversation) and outside any\n// session (a guide build). Read on each call, because it changes between turns\n// and between callers.\nexport interface SandboxActingUserIface {\n current(): Promise<string | null>;\n}\n\nexport const noSandboxActingUser: SandboxActingUserIface = { current: async () => null };\n\n// What an environment's pre-start reads (capabilities, mcpCatalog) are given.\nexport interface SandboxOfferContextIface {\n bindings?: HostedBindingsIface;\n organizationId: string;\n actingUser: SandboxActingUserIface;\n}\n\n// What an environment's hooks are given before anything starts.\nexport interface SandboxEnvironmentContextIface {\n bindings?: HostedBindingsIface;\n organizationId: string;\n guides: SandboxGuidesIface;\n}\n\n// Scoped by the host to this organization and provider. Providers can retain\n// reusable intermediate artifacts independently of a revision's seed files.\nexport interface SandboxArtifactsIface {\n get(key: string): Promise<JsonValue | null>;\n put(key: string, artifact: JsonValue): Promise<void>;\n}\n\nexport interface SandboxPreparationSourceIface {\n sourceRevision: string;\n read(): Promise<{ files: Record<string, string>; resources: Record<string, JsonValue> }>;\n}\n\nexport interface SandboxPrepareContextIface {\n bindings?: HostedBindingsIface;\n // A host-persisted resource source; artifacts may retain its identity instead of seed contents.\n preparation?: SandboxPreparationSourceIface;\n artifacts?: SandboxArtifactsIface;\n // Agent revisions supply workspace-relative seeds; setup-guide builds supply\n // guide.json and optional instructions.md. Resources name workspace, skills or guide.\n // Model instructions remain harness config.\n files: Record<string, string>;\n resources: Record<string, JsonValue>;\n sourceRevision: string;\n storagePath: string;\n organizationId: string;\n // The guide inputs (build-time) an environment names, resolved by the platform.\n guides: SandboxGuidesIface;\n // Who the session the artifact is prepared for acts for, for environments that\n // name a backend resource relative to that user; the key must then name it.\n actingUser: SandboxActingUserIface;\n log?: (message: string) => void;\n}\n\nexport interface SandboxStartContextIface {\n bindings?: HostedBindingsIface;\n /** Passive recovery only: never wake, create, seed, or restart backend services. */\n passive?: boolean;\n preparation?: SandboxPreparationSourceIface;\n session: {\n id: string;\n organizationId: string;\n conversationId: string | null;\n definitionId: string;\n bindingId: string;\n target: string;\n };\n storagePath: string;\n // Start-time inputs: guides, the variables to inject, repository credentials.\n guides: SandboxGuidesIface;\n variables: SandboxVariablesIface;\n repositories: SandboxRepositoriesIface;\n actingUser: SandboxActingUserIface;\n}\n\nexport enum SandboxSessionEndReason {\n Completed = 'completed',\n Expired = 'expired',\n Failed = 'failed',\n}\n\n// How long an environment's sandbox outlives a session: `session`\n// keeps it for the session's life; `conversation` gives every session in the\n// conversation one shared sandbox per target, surviving session resets;\n// `ephemeral` discards it when released.\nexport enum SandboxWorkspace {\n Session = 'session',\n Conversation = 'conversation',\n Ephemeral = 'ephemeral',\n}\n\nexport interface SandboxProviderImplementationIface<\n OpenOptions,\n Artifact extends JsonValue,\n State extends JsonValue,\n S extends NetworkSandboxSessionIface,\n> {\n // The workspace this environment declares, read before anything starts so the\n // session service knows which sessions share a binding. Absent or null: session.\n workspace?(ctx: SandboxEnvironmentContextIface): Promise<SandboxWorkspace | null>;\n // The capabilities this environment's sandboxes offer, read before anything\n // starts through the backend's own API. Absent or null: unknown\n // until started; local MCP is then not projected.\n capabilities?(ctx: SandboxOfferContextIface): Promise<SandboxCapability[] | null>;\n // The hosted MCP servers' tool catalogs the backend can give without starting\n // a sandbox (from its own records), so the MCP projection lists them from the\n // first `tools/list`. The projection checks a server's catalog against the\n // live server when a call first opens that server (servers a session never\n // uses stay closed) and announces a change with\n // `notifications/tools/list_changed`.\n //\n // Trade-off: a catalog left unknown (absent hook, null, or a null field) can\n // only be learned from the live sandbox, so the first `tools/list` that finds\n // it unknown starts the sandbox in the background, at session start rather\n // than on the first tool call. Otherwise those tools would never be listed,\n // and nothing would ever call them. Providers that can give the catalog keep\n // attach lazy.\n mcpCatalog?(ctx: SandboxOfferContextIface): Promise<SandboxMcpCatalogIface | null>;\n // Reads committed files without starting/resuming a sandbox. Null means the backend\n // is live or offers no snapshot. An unavailable sleeping snapshot must throw,\n // never fall through to a read that wakes it. Pin subsequent ranges by snapshotId.\n readSnapshot?(\n ctx: SandboxOfferContextIface,\n state: State,\n request: SandboxSnapshotRequestIface,\n ): Promise<SandboxSnapshotResponseIface | null>;\n // Inspect retained backend processes without opening, resuming or extending a sandbox.\n // Stop requires execute access; the provider also enforces backend ownership.\n processes?(\n ctx: SandboxOfferContextIface & { bindingId: string },\n state: State,\n request: ProcessInspectionRequestIface,\n ): Promise<ProcessInspectionResultIface>;\n // Browser editor for this provider's existing workspace. The host checks write\n // authorization; this hook never creates or wakes a backend. Credentials stay\n // in the authentication form, never the editor URL or stored provider state.\n editor?(\n ctx: SandboxOfferContextIface,\n state: State,\n request: SandboxEditorRequestIface,\n ): Promise<SandboxEditorResultIface>;\n // Content-addressed by `artifactKey`; the session service caches artifacts in\n // agent.sandbox_artifacts and calls prepare only on a miss.\n artifactKey(ctx: SandboxPrepareContextIface): Promise<string>;\n prepare(ctx: SandboxPrepareContextIface): Promise<Artifact>;\n // `region`: where the backend placed the sandbox (its own region name), so the\n // session service can place the harness near it; null when unknown.\n start(\n ctx: SandboxStartContextIface,\n options: OpenOptions | undefined,\n artifact: Artifact,\n ): Promise<{ handle: SandboxProviderHandleIface<S>; state: State; region?: string | null }>;\n resume(\n ctx: SandboxStartContextIface,\n artifact: Artifact,\n state: State,\n ): Promise<SandboxProviderHandleIface<S>>;\n // Reconnect to an already running backend after host restart for a read-only viewer.\n // Absent: viewers can use a retained live handle but cannot trigger resume.\n resumePassive?(\n ctx: SandboxStartContextIface,\n artifact: Artifact,\n state: State,\n ): Promise<SandboxProviderHandleIface<S>>;\n // Park: pause or stop the sandbox, returning the state resume needs.\n park?(ctx: SandboxStartContextIface, artifact: Artifact, state: State): Promise<State>;\n onSessionEnd?(\n ctx: SandboxStartContextIface,\n artifact: Artifact,\n state: State,\n options: { reason: SandboxSessionEndReason },\n ): Promise<void>;\n}\n\nexport interface SandboxProviderDefinitionIface<\n EnvOptions,\n OpenOptions,\n Artifact extends JsonValue,\n State extends JsonValue,\n S extends NetworkSandboxSessionIface,\n> {\n name: string;\n // The version of `State`'s shape. The session service records it with each\n // binding and refuses to resume a state written under another version (the\n // next call starts the sandbox again instead).\n stateProtocolVersion?: number;\n environment(\n options?: EnvOptions,\n ): SandboxProviderImplementationIface<OpenOptions, Artifact, State, S>;\n}\n\n// A defined provider: the definition plus authoring sugar. `environment(opts)`\n// returns an environment whose `.open(openOptions)` records a sandbox binding\n// target when authored, and is what the session service drives at run time.\nexport interface SandboxProviderIface<\n EnvOptions,\n OpenOptions,\n Artifact extends JsonValue,\n State extends JsonValue,\n S extends NetworkSandboxSessionIface,\n> {\n readonly definition: SandboxProviderDefinitionIface<EnvOptions, OpenOptions, Artifact, State, S>;\n readonly name: string;\n environment(options?: EnvOptions): AwaitableSandboxEnvironmentIface<EnvOptions, OpenOptions>;\n}\n\nexport interface SandboxEnvironmentIface<EnvOptions, OpenOptions> {\n readonly providerName: string;\n readonly options: EnvOptions | undefined;\n // Provider-authored notices shown by the compiler and Build before publication.\n readonly authoringWarnings?: readonly string[];\n // Authoring: records the open options (access, ...) for this target.\n open(options?: OpenOptions): SandboxOpenRequestIface<EnvOptions, OpenOptions>;\n}\n\n// An environment whose open request a sandbox.ts selector can await to get\n// the live session (open-scope.ts); what defineSandboxProvider and the\n// installed helpers return.\nexport interface AwaitableSandboxEnvironmentIface<\n EnvOptions,\n OpenOptions,\n> extends SandboxEnvironmentIface<EnvOptions, OpenOptions> {\n open(options?: OpenOptions): AwaitableSandboxOpenRequestIface<EnvOptions, OpenOptions>;\n}\n\nexport interface SandboxOpenRequestIface<EnvOptions, OpenOptions> {\n readonly providerName: string;\n readonly environmentOptions: EnvOptions | undefined;\n readonly openOptions: OpenOptions | undefined;\n readonly authoringWarnings?: readonly string[];\n}\n\nexport const defineSandboxProvider = <\n EnvOptions,\n OpenOptions,\n Artifact extends JsonValue,\n State extends JsonValue,\n S extends NetworkSandboxSessionIface,\n>(\n definition: SandboxProviderDefinitionIface<EnvOptions, OpenOptions, Artifact, State, S>,\n): SandboxProviderIface<EnvOptions, OpenOptions, Artifact, State, S> => ({\n definition,\n name: definition.name,\n environment: (options) => ({\n providerName: definition.name,\n options,\n open: (openOptions) =>\n awaitableOpenRequest({\n providerName: definition.name,\n environmentOptions: options,\n openOptions,\n }),\n }),\n});\n\n// Erased form the session service stores in its provider registry.\nexport type AnySandboxProviderIface = SandboxProviderIface<\n JsonValue,\n JsonValue,\n JsonValue,\n JsonValue,\n NetworkSandboxSessionIface\n>;\n\n// Events emitted through a sandbox provider's process lifecycle.\nexport enum SandboxEventKind {\n ProcessExited = 'process_exited',\n}\n"],
|
|
5
|
+
"mappings": "AAQA,SAAS,4BAAmE;AAoCrE,IAAK,mBAAL,kBAAKA,sBAAL;AACL,EAAAA,kBAAA,UAAO;AACP,EAAAA,kBAAA,eAAY;AACZ,EAAAA,kBAAA,aAAU;AACV,EAAAA,kBAAA,WAAQ;AAJE,SAAAA;AAAA,GAAA;AAkEL,IAAK,gBAAL,kBAAKC,mBAAL;AACL,EAAAA,eAAA,cAAW;AACX,EAAAA,eAAA,aAAU;AACV,EAAAA,eAAA,eAAY;AAHF,SAAAA;AAAA,GAAA;AAWL,IAAK,eAAL,kBAAKC,kBAAL;AACL,EAAAA,cAAA,UAAO;AACP,EAAAA,cAAA,WAAQ;AACR,EAAAA,cAAA,QAAK;AAHK,SAAAA;AAAA,GAAA;AAyCL,MAAM,uBAAuB,CAClC,aACwC,aAAa;AAgChD,IAAK,oBAAL,kBAAKC,uBAAL;AACL,EAAAA,mBAAA,WAAQ;AACR,EAAAA,mBAAA,aAAU;AACV,EAAAA,mBAAA,WAAQ;AACR,EAAAA,mBAAA,mBAAgB;AAChB,EAAAA,mBAAA,iBAAc;AACd,EAAAA,mBAAA,YAAS;AACT,EAAAA,mBAAA,cAAW;AACX,EAAAA,mBAAA,aAAU;AARA,SAAAA;AAAA,GAAA;AAwEL,MAAM,kBAAsC;AAAA,EACjD,KAAK,YAAY;AAAA,EACjB,SAAS,YAAY;AACvB;AAEO,MAAM,wBAAkD;AAAA,EAC7D,aAAa,YAAY;AAC3B;AAEO,MAAM,qBAA4C,EAAE,KAAK,YAAY,KAAK;AAY1E,MAAM,sBAA8C,EAAE,SAAS,YAAY,KAAK;AAsEhF,IAAK,0BAAL,kBAAKC,6BAAL;AACL,EAAAA,yBAAA,eAAY;AACZ,EAAAA,yBAAA,aAAU;AACV,EAAAA,yBAAA,YAAS;AAHC,SAAAA;AAAA,GAAA;AAUL,IAAK,mBAAL,kBAAKC,sBAAL;AACL,EAAAA,kBAAA,aAAU;AACV,EAAAA,kBAAA,kBAAe;AACf,EAAAA,kBAAA,eAAY;AAHF,SAAAA;AAAA,GAAA;AAmJL,MAAM,wBAAwB,CAOnC,gBACuE;AAAA,EACvE;AAAA,EACA,MAAM,WAAW;AAAA,EACjB,aAAa,CAAC,aAAa;AAAA,IACzB,cAAc,WAAW;AAAA,IACzB;AAAA,IACA,MAAM,CAAC,gBACL,qBAAqB;AAAA,MACnB,cAAc,WAAW;AAAA,MACzB,oBAAoB;AAAA,MACpB;AAAA,IACF,CAAC;AAAA,EACL;AACF;AAYO,IAAK,mBAAL,kBAAKC,sBAAL;AACL,EAAAA,kBAAA,mBAAgB;AADN,SAAAA;AAAA,GAAA;",
|
|
6
6
|
"names": ["SandboxEntryType", "NetworkPolicy", "PortProtocol", "SandboxCapability", "SandboxSessionEndReason", "SandboxWorkspace", "SandboxEventKind"]
|
|
7
7
|
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { HttpMcpServerBindingIface, ToolAnnotationRuleIface, ToolAnnotationSelectorIface, ToolDescriptorIface } from "./manifest.mjs";
|
|
2
|
+
export type ToolAnnotationsIface = NonNullable<ToolDescriptorIface['annotations']>;
|
|
3
|
+
export declare const toolAnnotationsMatch: (selector: ToolAnnotationSelectorIface, annotations: ToolAnnotationsIface | undefined) => boolean;
|
|
4
|
+
type AnnotationPolicyIface = Pick<HttpMcpServerBindingIface, 'allowAnnotations' | 'denyAnnotations'>;
|
|
5
|
+
export declare const isToolHiddenByAnnotations: (binding: AnnotationPolicyIface, annotations: ToolAnnotationsIface | undefined) => boolean;
|
|
6
|
+
export declare const toolAnnotationRuleFor: (binding: AnnotationPolicyIface, annotations: ToolAnnotationsIface | undefined) => ToolAnnotationRuleIface | undefined;
|
|
7
|
+
export {};
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
const hintMatches = (wanted, actual, fallback) => wanted == null || (actual ?? fallback) === wanted;
|
|
2
|
+
const toolAnnotationsMatch = (selector, annotations) => hintMatches(selector.readOnlyHint, annotations?.readOnlyHint, false) && hintMatches(selector.destructiveHint, annotations?.destructiveHint, true) && hintMatches(selector.idempotentHint, annotations?.idempotentHint, false) && hintMatches(selector.openWorldHint, annotations?.openWorldHint, true);
|
|
3
|
+
const isToolHiddenByAnnotations = (binding, annotations) => binding.denyAnnotations?.some((selector) => toolAnnotationsMatch(selector, annotations)) === true;
|
|
4
|
+
const toolAnnotationRuleFor = (binding, annotations) => binding.allowAnnotations?.find((rule) => toolAnnotationsMatch(rule.match, annotations));
|
|
5
|
+
export {
|
|
6
|
+
isToolHiddenByAnnotations,
|
|
7
|
+
toolAnnotationRuleFor,
|
|
8
|
+
toolAnnotationsMatch
|
|
9
|
+
};
|
|
10
|
+
//# sourceMappingURL=tool-annotations.mjs.map
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": 3,
|
|
3
|
+
"sources": ["../../../../src/tool-annotations.ts"],
|
|
4
|
+
"sourcesContent": ["import type {\n HttpMcpServerBindingIface,\n ToolAnnotationRuleIface,\n ToolAnnotationSelectorIface,\n ToolDescriptorIface,\n} from \"./manifest.mjs\";\n\n// Selecting connection tools by their MCP annotations. A selector matches when\n// every hint it sets equals the tool's hint, reading a hint the tool omits as\n// the MCP spec's default (not read-only, destructive, not idempotent, open\n// world), so an unannotated tool never passes `{ readOnlyHint: true }`.\n// Annotations come from the connection's server: select on them only for\n// servers you trust to classify their own tools.\n\nexport type ToolAnnotationsIface = NonNullable<ToolDescriptorIface['annotations']>;\n\nconst hintMatches = (\n wanted: boolean | undefined,\n actual: boolean | undefined,\n fallback: boolean,\n): boolean => wanted == null || (actual ?? fallback) === wanted;\n\nexport const toolAnnotationsMatch = (\n selector: ToolAnnotationSelectorIface,\n annotations: ToolAnnotationsIface | undefined,\n): boolean =>\n hintMatches(selector.readOnlyHint, annotations?.readOnlyHint, false) &&\n hintMatches(selector.destructiveHint, annotations?.destructiveHint, true) &&\n hintMatches(selector.idempotentHint, annotations?.idempotentHint, false) &&\n hintMatches(selector.openWorldHint, annotations?.openWorldHint, true);\n\ntype AnnotationPolicyIface = Pick<\n HttpMcpServerBindingIface,\n 'allowAnnotations' | 'denyAnnotations'\n>;\n\nexport const isToolHiddenByAnnotations = (\n binding: AnnotationPolicyIface,\n annotations: ToolAnnotationsIface | undefined,\n): boolean =>\n binding.denyAnnotations?.some((selector) => toolAnnotationsMatch(selector, annotations)) === true;\n\n// The first allow rule a tool's annotations match: hosts expose the tool with\n// its approval when no approvals key already covers it.\nexport const toolAnnotationRuleFor = (\n binding: AnnotationPolicyIface,\n annotations: ToolAnnotationsIface | undefined,\n): ToolAnnotationRuleIface | undefined =>\n binding.allowAnnotations?.find((rule) => toolAnnotationsMatch(rule.match, annotations));\n"],
|
|
5
|
+
"mappings": "AAgBA,MAAM,cAAc,CAClB,QACA,QACA,aACY,UAAU,SAAS,UAAU,cAAc;AAElD,MAAM,uBAAuB,CAClC,UACA,gBAEA,YAAY,SAAS,cAAc,aAAa,cAAc,KAAK,KACnE,YAAY,SAAS,iBAAiB,aAAa,iBAAiB,IAAI,KACxE,YAAY,SAAS,gBAAgB,aAAa,gBAAgB,KAAK,KACvE,YAAY,SAAS,eAAe,aAAa,eAAe,IAAI;AAO/D,MAAM,4BAA4B,CACvC,SACA,gBAEA,QAAQ,iBAAiB,KAAK,CAAC,aAAa,qBAAqB,UAAU,WAAW,CAAC,MAAM;AAIxF,MAAM,wBAAwB,CACnC,SACA,gBAEA,QAAQ,kBAAkB,KAAK,CAAC,SAAS,qBAAqB,KAAK,OAAO,WAAW,CAAC;",
|
|
6
|
+
"names": []
|
|
7
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { ToolApproval, type HttpMcpServerBindingIface } from "./manifest.mjs";
|
|
2
|
+
export declare const TOOL_PATTERN_WILDCARD = "*";
|
|
3
|
+
export declare const isToolPattern: (key: string) => boolean;
|
|
4
|
+
export declare const toolPatternMatches: (pattern: string, name: string) => boolean;
|
|
5
|
+
export declare const resolveToolApprovalKey: (approvals: Readonly<Record<string, ToolApproval>>, name: string) => string | undefined;
|
|
6
|
+
export declare const isToolDenied: (deny: readonly string[] | undefined, name: string) => boolean;
|
|
7
|
+
type ConnectionPolicyIface = Pick<HttpMcpServerBindingIface, 'approvals' | 'deny'>;
|
|
8
|
+
export declare const isToolExposed: (binding: ConnectionPolicyIface, name: string) => boolean;
|
|
9
|
+
export declare const isToolLoaded: (binding: Pick<HttpMcpServerBindingIface, "load">, name: string) => boolean;
|
|
10
|
+
export declare const toolApprovalOf: (binding: ConnectionPolicyIface, name: string) => ToolApproval;
|
|
11
|
+
export {};
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import { ToolApproval } from "./manifest.mjs";
|
|
2
|
+
const TOOL_PATTERN_WILDCARD = "*";
|
|
3
|
+
const isToolPattern = (key) => key.includes(TOOL_PATTERN_WILDCARD);
|
|
4
|
+
const toolPatternMatches = (pattern, name) => {
|
|
5
|
+
let patternIndex = 0;
|
|
6
|
+
let nameIndex = 0;
|
|
7
|
+
let starIndex = -1;
|
|
8
|
+
let resumeIndex = 0;
|
|
9
|
+
while (nameIndex < name.length) {
|
|
10
|
+
const char = pattern[patternIndex];
|
|
11
|
+
if (char === TOOL_PATTERN_WILDCARD) {
|
|
12
|
+
starIndex = patternIndex;
|
|
13
|
+
resumeIndex = nameIndex;
|
|
14
|
+
patternIndex += 1;
|
|
15
|
+
} else if (char != null && char === name[nameIndex]) {
|
|
16
|
+
patternIndex += 1;
|
|
17
|
+
nameIndex += 1;
|
|
18
|
+
} else if (starIndex !== -1) {
|
|
19
|
+
patternIndex = starIndex + 1;
|
|
20
|
+
resumeIndex += 1;
|
|
21
|
+
nameIndex = resumeIndex;
|
|
22
|
+
} else {
|
|
23
|
+
return false;
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
while (pattern[patternIndex] === TOOL_PATTERN_WILDCARD) patternIndex += 1;
|
|
27
|
+
return patternIndex === pattern.length;
|
|
28
|
+
};
|
|
29
|
+
const literalLength = (pattern) => pattern.length - pattern.split(TOOL_PATTERN_WILDCARD).length + 1;
|
|
30
|
+
const resolveToolApprovalKey = (approvals, name) => {
|
|
31
|
+
if (Object.hasOwn(approvals, name)) return name;
|
|
32
|
+
let best;
|
|
33
|
+
for (const key of Object.keys(approvals)) {
|
|
34
|
+
if (!isToolPattern(key) || !toolPatternMatches(key, name)) continue;
|
|
35
|
+
if (best == null) {
|
|
36
|
+
best = key;
|
|
37
|
+
continue;
|
|
38
|
+
}
|
|
39
|
+
const specificity = literalLength(key) - literalLength(best);
|
|
40
|
+
if (specificity > 0) best = key;
|
|
41
|
+
if (specificity !== 0) continue;
|
|
42
|
+
const stricter = approvals[key] === ToolApproval.Ask && approvals[best] !== ToolApproval.Ask;
|
|
43
|
+
const looser = approvals[key] !== ToolApproval.Ask && approvals[best] === ToolApproval.Ask;
|
|
44
|
+
if (stricter || !looser && key < best) best = key;
|
|
45
|
+
}
|
|
46
|
+
return best;
|
|
47
|
+
};
|
|
48
|
+
const isToolDenied = (deny, name) => deny?.some((pattern) => toolPatternMatches(pattern, name)) === true;
|
|
49
|
+
const isToolExposed = (binding, name) => !isToolDenied(binding.deny, name) && (binding.approvals == null || resolveToolApprovalKey(binding.approvals, name) != null);
|
|
50
|
+
const isToolLoaded = (binding, name) => binding.load == null || binding.load.some((pattern) => toolPatternMatches(pattern, name));
|
|
51
|
+
const toolApprovalOf = (binding, name) => {
|
|
52
|
+
const key = binding.approvals == null ? void 0 : resolveToolApprovalKey(binding.approvals, name);
|
|
53
|
+
return key == null ? ToolApproval.Allow : binding.approvals?.[key] ?? ToolApproval.Allow;
|
|
54
|
+
};
|
|
55
|
+
export {
|
|
56
|
+
TOOL_PATTERN_WILDCARD,
|
|
57
|
+
isToolDenied,
|
|
58
|
+
isToolExposed,
|
|
59
|
+
isToolLoaded,
|
|
60
|
+
isToolPattern,
|
|
61
|
+
resolveToolApprovalKey,
|
|
62
|
+
toolApprovalOf,
|
|
63
|
+
toolPatternMatches
|
|
64
|
+
};
|
|
65
|
+
//# sourceMappingURL=tool-patterns.mjs.map
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": 3,
|
|
3
|
+
"sources": ["../../../../src/tool-patterns.ts"],
|
|
4
|
+
"sourcesContent": ["import { ToolApproval, type HttpMcpServerBindingIface } from \"./manifest.mjs\";\n\n// Tool-name patterns for an HTTP MCP connection's `approvals`, `deny` and\n// `inputApprovals` keys. `*` matches any run of characters, including none;\n// every other character matches itself. MCP tool names are letters, digits,\n// `_`, `-` and `.`, so `*` never collides with a real name. Hosts resolve\n// connection policy through these helpers so every host applies one rule.\n\nexport const TOOL_PATTERN_WILDCARD = '*';\n\nexport const isToolPattern = (key: string): boolean => key.includes(TOOL_PATTERN_WILDCARD);\n\n// Wildcard matching with a single backtrack point: linear in practice for `*` globs.\nexport const toolPatternMatches = (pattern: string, name: string): boolean => {\n let patternIndex = 0;\n let nameIndex = 0;\n let starIndex = -1;\n let resumeIndex = 0;\n while (nameIndex < name.length) {\n const char = pattern[patternIndex];\n if (char === TOOL_PATTERN_WILDCARD) {\n starIndex = patternIndex;\n resumeIndex = nameIndex;\n patternIndex += 1;\n } else if (char != null && char === name[nameIndex]) {\n patternIndex += 1;\n nameIndex += 1;\n } else if (starIndex !== -1) {\n patternIndex = starIndex + 1;\n resumeIndex += 1;\n nameIndex = resumeIndex;\n } else {\n return false;\n }\n }\n while (pattern[patternIndex] === TOOL_PATTERN_WILDCARD) patternIndex += 1;\n return patternIndex === pattern.length;\n};\n\nconst literalLength = (pattern: string): number =>\n pattern.length - pattern.split(TOOL_PATTERN_WILDCARD).length + 1;\n\n// The approvals key that governs `name`: the exact key, else the matching\n// pattern with the most literal characters. Equally specific patterns resolve\n// to the stricter policy (Ask), then lexically, so the result never depends on\n// key order. Undefined when no key matches.\nexport const resolveToolApprovalKey = (\n approvals: Readonly<Record<string, ToolApproval>>,\n name: string,\n): string | undefined => {\n if (Object.hasOwn(approvals, name)) return name;\n let best: string | undefined;\n for (const key of Object.keys(approvals)) {\n if (!isToolPattern(key) || !toolPatternMatches(key, name)) continue;\n if (best == null) {\n best = key;\n continue;\n }\n const specificity = literalLength(key) - literalLength(best);\n if (specificity > 0) best = key;\n if (specificity !== 0) continue;\n const stricter = approvals[key] === ToolApproval.Ask && approvals[best] !== ToolApproval.Ask;\n const looser = approvals[key] !== ToolApproval.Ask && approvals[best] === ToolApproval.Ask;\n if (stricter || (!looser && key < best)) best = key;\n }\n return best;\n};\n\nexport const isToolDenied = (deny: readonly string[] | undefined, name: string): boolean =>\n deny?.some((pattern) => toolPatternMatches(pattern, name)) === true;\n\ntype ConnectionPolicyIface = Pick<HttpMcpServerBindingIface, 'approvals' | 'deny'>;\n\n// Whether the connection exposes `name` at all. Null approvals expose every\n// listed tool; `deny` wins over any approvals key.\nexport const isToolExposed = (binding: ConnectionPolicyIface, name: string): boolean =>\n !isToolDenied(binding.deny, name) &&\n (binding.approvals == null || resolveToolApprovalKey(binding.approvals, name) != null);\n\n// Whether the harness lists an exposed tool up front (`load` names or\n// patterns); hosts keep the others reachable through search. Callers check\n// exposure first.\nexport const isToolLoaded = (\n binding: Pick<HttpMcpServerBindingIface, 'load'>,\n name: string,\n): boolean =>\n binding.load == null || binding.load.some((pattern) => toolPatternMatches(pattern, name));\n\n// The connection's approval for an exposed tool; Allow when nothing matches.\nexport const toolApprovalOf = (binding: ConnectionPolicyIface, name: string): ToolApproval => {\n const key =\n binding.approvals == null ? undefined : resolveToolApprovalKey(binding.approvals, name);\n return key == null ? ToolApproval.Allow : (binding.approvals?.[key] ?? ToolApproval.Allow);\n};\n"],
|
|
5
|
+
"mappings": "AAAA,SAAS,oBAAoD;AAQtD,MAAM,wBAAwB;AAE9B,MAAM,gBAAgB,CAAC,QAAyB,IAAI,SAAS,qBAAqB;AAGlF,MAAM,qBAAqB,CAAC,SAAiB,SAA0B;AAC5E,MAAI,eAAe;AACnB,MAAI,YAAY;AAChB,MAAI,YAAY;AAChB,MAAI,cAAc;AAClB,SAAO,YAAY,KAAK,QAAQ;AAC9B,UAAM,OAAO,QAAQ,YAAY;AACjC,QAAI,SAAS,uBAAuB;AAClC,kBAAY;AACZ,oBAAc;AACd,sBAAgB;AAAA,IAClB,WAAW,QAAQ,QAAQ,SAAS,KAAK,SAAS,GAAG;AACnD,sBAAgB;AAChB,mBAAa;AAAA,IACf,WAAW,cAAc,IAAI;AAC3B,qBAAe,YAAY;AAC3B,qBAAe;AACf,kBAAY;AAAA,IACd,OAAO;AACL,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO,QAAQ,YAAY,MAAM,sBAAuB,iBAAgB;AACxE,SAAO,iBAAiB,QAAQ;AAClC;AAEA,MAAM,gBAAgB,CAAC,YACrB,QAAQ,SAAS,QAAQ,MAAM,qBAAqB,EAAE,SAAS;AAM1D,MAAM,yBAAyB,CACpC,WACA,SACuB;AACvB,MAAI,OAAO,OAAO,WAAW,IAAI,EAAG,QAAO;AAC3C,MAAI;AACJ,aAAW,OAAO,OAAO,KAAK,SAAS,GAAG;AACxC,QAAI,CAAC,cAAc,GAAG,KAAK,CAAC,mBAAmB,KAAK,IAAI,EAAG;AAC3D,QAAI,QAAQ,MAAM;AAChB,aAAO;AACP;AAAA,IACF;AACA,UAAM,cAAc,cAAc,GAAG,IAAI,cAAc,IAAI;AAC3D,QAAI,cAAc,EAAG,QAAO;AAC5B,QAAI,gBAAgB,EAAG;AACvB,UAAM,WAAW,UAAU,GAAG,MAAM,aAAa,OAAO,UAAU,IAAI,MAAM,aAAa;AACzF,UAAM,SAAS,UAAU,GAAG,MAAM,aAAa,OAAO,UAAU,IAAI,MAAM,aAAa;AACvF,QAAI,YAAa,CAAC,UAAU,MAAM,KAAO,QAAO;AAAA,EAClD;AACA,SAAO;AACT;AAEO,MAAM,eAAe,CAAC,MAAqC,SAChE,MAAM,KAAK,CAAC,YAAY,mBAAmB,SAAS,IAAI,CAAC,MAAM;AAM1D,MAAM,gBAAgB,CAAC,SAAgC,SAC5D,CAAC,aAAa,QAAQ,MAAM,IAAI,MAC/B,QAAQ,aAAa,QAAQ,uBAAuB,QAAQ,WAAW,IAAI,KAAK;AAK5E,MAAM,eAAe,CAC1B,SACA,SAEA,QAAQ,QAAQ,QAAQ,QAAQ,KAAK,KAAK,CAAC,YAAY,mBAAmB,SAAS,IAAI,CAAC;AAGnF,MAAM,iBAAiB,CAAC,SAAgC,SAA+B;AAC5F,QAAM,MACJ,QAAQ,aAAa,OAAO,SAAY,uBAAuB,QAAQ,WAAW,IAAI;AACxF,SAAO,OAAO,OAAO,aAAa,QAAS,QAAQ,YAAY,GAAG,KAAK,aAAa;AACtF;",
|
|
6
|
+
"names": []
|
|
7
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@finalai/agent-provider",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.4",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "Provider contracts for the agent stack: harnesses, sandboxes (handle, wire, MCP projection), channels, credential policies, and the conformance kit.",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
"README.md",
|
|
10
10
|
"LICENSE",
|
|
11
11
|
"NOTICE",
|
|
12
|
+
"HOSTING.md",
|
|
12
13
|
"THIRD_PARTY_NOTICES.md"
|
|
13
14
|
],
|
|
14
15
|
"type": "module",
|
|
@@ -182,8 +183,8 @@
|
|
|
182
183
|
},
|
|
183
184
|
"dependencies": {
|
|
184
185
|
"@agentclientprotocol/sdk": "1.8.0",
|
|
185
|
-
"@finalai/acp-session": "0.1.
|
|
186
|
-
"@finalai/agent-protocol": "0.1.
|
|
186
|
+
"@finalai/acp-session": "0.1.4",
|
|
187
|
+
"@finalai/agent-protocol": "0.1.4",
|
|
187
188
|
"@modelcontextprotocol/client": "^2.1.0",
|
|
188
189
|
"@modelcontextprotocol/core": "^2.1.0",
|
|
189
190
|
"@modelcontextprotocol/server": "^2.1.0",
|