SharedOS API / @aicoo/sharedos-runtime

@aicoo/sharedos-runtime

A fixed permission envelope with standard and replaceable one-turn agent runtimes.

npm install @aicoo/sharedos-runtime@next

SharedOS is runtime-agnostic, not runtime-less. The package exports two layers:

SharedOSExecutor validates and admits a turn, exposes only authorized tools, rechecks every exact call, applies cancellation, and records runtime provenance. Runtime plugins cannot replace this layer.
RuntimePlugin owns the agent loop inside that envelope. StandardRuntime is the included reference implementation over AgentTurnDriver.

Standard runtime

import { SharedOSExecutor, StandardRuntime } from "@aicoo/sharedos-runtime";

const runtime = new StandardRuntime(agentDriver);
const turns = new SharedOSExecutor(kernel, runtime, {
  defaultMaxSteps: 16,
  defaultMaxToolCalls: 16,
  defaultTimeoutMs: 120_000,
});

const result = await turns.execute(executionRequest);

The original API remains available as a compatibility shorthand, retained pending a deprecation decision (docs/open-items.md):

import { TurnExecutor } from "@aicoo/sharedos-runtime";

const turns = new TurnExecutor(kernel, agentDriver);

A turn may end by asking a human to decide (ADR 0011, ADR 0017). The ask is a catalogued tool, sharedos.escalate, so that it is chosen rather than inferred from prose, and so that it is permission-filtered like every other tool:

import { createEscalationTool } from "@aicoo/sharedos-runtime";

kernel.registerTool(createEscalationTool());

An agent sees it only when its context enables the sharedos tool namespace and it holds a grant over resource sharedos / ["escalation"], action request — exported as ESCALATION_TOOL_NAMESPACE, ESCALATION_RESOURCE_PATH, and ESCALATION_ACTION. A host that issues no such grant has agents that cannot escalate, which is the intended arrangement.

The tool is never executed. A driver whose turn's catalogue offers it recognises the name with escalationRequest(tool, arguments) and returns { type: "escalate", reason } instead of a tool call; StandardRuntime settles the turn as escalated, the envelope records escalation.requested, and nothing is granted while the ask is pending. Without the grant the name is passed through and refused tool_unavailable, and SharedOSExecutor refuses an escalate outcome from any plugin on such a turn — the catalogue gates the name, not the driver's goodwill. The registered handler exists to put the tool in the catalogue and to fail — escalation_not_terminated — if a driver forwards the call anyway. Over MCP the bridge answers the ask itself and refuses later calls on that turn with escalation_pending (ADR 0018).

Custom runtime

import type { RuntimePlugin } from "@aicoo/sharedos-runtime";

const codexRuntime: RuntimePlugin = {
  manifest: {
    id: "acme.codex",
    version: "1.0.0",
    protocolVersion: "1",
    metadata: { harness: "codex", backend: "vercel-sandbox" },
  },
  async run(request, host, signal) {
    // Translate the harness's native tool definitions to request.tools.
    // Every implementation must route actual effects through this broker.
    const result = await host.invokeTool({
      id: crypto.randomUUID(),
      tool: "files.search",
      arguments: { path: ["Projects"], query: "status" },
      traceId: request.context.traceId,
      requestedAt: request.context.now,
    });

    signal.throwIfAborted();
    return { type: "complete", output: { toolStatus: result.status } };
  },
};

const turns = new SharedOSExecutor(kernel, codexRuntime);

Embedded hosts can observe events as they are emitted without giving the plugin an authoritative event channel:

await turns.execute(executionRequest, {
  signal,
  onEvent: (event) => streamController.enqueue(event),
});

The callback receives a frozen snapshot. Callback failure does not replace the turn's protocol outcome; cancel the supplied signal when the consumer closes.

A plugin receives a frozen RuntimeTurnRequest without grants, issuing authority, or namespace-management state. Its RuntimeHost contains only:

effective step, tool-call, and deadline limits;
invokeTool, which checks the visible catalog and then re-authorizes through the kernel;
emit, which records plugin observations as wrapped runtime.event events.

The broker closes when run returns. A plugin cannot use a retained host handle for later tool calls or emit authoritative turn.* and tool.* events.

Trusted selection

RuntimeRegistry is an instance-scoped registry for trusted boot configuration:

const runtimes = new RuntimeRegistry([
  new StandardRuntime(agentDriver),
  codexRuntime,
]);
const runtime = runtimes.resolve(serverPolicy.runtimeId);
const turns = new SharedOSExecutor(kernel, runtime);

Do not resolve a runtime id directly from a message, model output, or unverified request metadata. In-process plugins have the ambient privileges of the host; isolate third-party runtimes behind a process, container, microVM, or remote adapter.

Product heartbeats, multi-turn retries, adaptive routing, benchmark scheduling, and network-level stopping remain host responsibilities.

SharedOS is currently an 0.x prerelease.

Classes

RuntimeNotFoundError

Defined in: packages/runtime/src/runtime-plugin.ts:158

Extends

Error

Constructors

Constructor

new RuntimeNotFoundError(runtimeId): RuntimeNotFoundError

Defined in: packages/runtime/src/runtime-plugin.ts:159

Parameters

Parameter	Type
`runtimeId`	`string`

Property	Modifier	Type	Description	Inherited from	Defined in
<a id="property-cause"></a> `cause?`	`public`	`unknown`	-	`Error.cause`	node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es2022.error.d.ts:26
<a id="property-message"></a> `message`	`public`	`string`	-	`Error.message`	node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1077
<a id="property-name"></a> `name`	`public`	`string`	-	`Error.name`	node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1076
<a id="property-stack"></a> `stack?`	`public`	`string`	-	`Error.stack`	node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.es5.d.ts:1078
<a id="property-stacktracelimit"></a> `stackTraceLimit`	`static`	`number`	The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.	`Error.stackTraceLimit`	node_modules/.pnpm/@types+node@22.20.1/node_modules/@types/node/globals.d.ts:68

Parameter	Type
`kernel`	`TurnKernel`
`runtime`	`RuntimePlugin`
`options`	`SharedOSExecutorOptions`

Parameter	Type
`input`	{ `agent`: { `agentId`: `string`; `kind`: `"agent"`; }; `context`: { `actor`: { `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }; `authority`: { `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }; `enabledToolNamespaces`: `string`[]; `namespaceId`: `string`; `now`: `string`; `owner`: { `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }; `purpose`: `string`; `traceId`: `string`; }; `executionId`: `string`; `message`: { `createdAt`: `string`; `id`: `string`; `payload`: `JsonValue`; `provenance?`: { `metadata?`: `JsonObject`; `parentIds`: `string`[]; `source`: `string`; }; `purpose`: `string`; `receiver`: { `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }; `replyTo?`: `string`; `sender`: { `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }; `traceId`: `string`; `version`: `"1"`; }; `metadata?`: `JsonObject`; `options?`: { `maxSteps?`: `number`; `maxToolCalls?`: `number`; `timeoutMs?`: `number`; }; `state?`: `JsonObject`; `tools`: `object`[]; `version`: `"1"`; }
`input.agent`	{ `agentId`: `string`; `kind`: `"agent"`; }
`input.agent.agentId`	`string`
`input.agent.kind`	`"agent"`
`input.context`	{ `actor`: { `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }; `authority`: { `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }; `enabledToolNamespaces`: `string`[]; `namespaceId`: `string`; `now`: `string`; `owner`: { `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }; `purpose`: `string`; `traceId`: `string`; }
`input.context.actor`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }
`input.context.authority`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }
`input.context.enabledToolNamespaces`	`string`[]
`input.context.namespaceId`	`string`
`input.context.now`	`string`
`input.context.owner`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }
`input.context.purpose`	`string`
`input.context.traceId`	`string`
`input.executionId`	`string`
`input.message`	{ `createdAt`: `string`; `id`: `string`; `payload`: `JsonValue`; `provenance?`: { `metadata?`: `JsonObject`; `parentIds`: `string`[]; `source`: `string`; }; `purpose`: `string`; `receiver`: { `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }; `replyTo?`: `string`; `sender`: { `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }; `traceId`: `string`; `version`: `"1"`; }
`input.message.createdAt`	`string`
`input.message.id`	`string`
`input.message.payload`	`JsonValue`
`input.message.provenance?`	{ `metadata?`: `JsonObject`; `parentIds`: `string`[]; `source`: `string`; }
`input.message.provenance.metadata?`	`JsonObject`
`input.message.provenance.parentIds`	`string`[]
`input.message.provenance.source`	`string`
`input.message.purpose`	`string`
`input.message.receiver`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }
`input.message.replyTo?`	`string`
`input.message.sender`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }
`input.message.traceId`	`string`
`input.message.version`	`"1"`
`input.metadata?`	`JsonObject`
`input.options?`	{ `maxSteps?`: `number`; `maxToolCalls?`: `number`; `timeoutMs?`: `number`; }
`input.options.maxSteps?`	`number`
`input.options.maxToolCalls?`	`number`
`input.options.timeoutMs?`	`number`
`input.state?`	`JsonObject`
`input.tools`	`object`[]
`input.version`	`"1"`
`options`	`ExecuteTurnOptions`

Property	Modifier	Type	Default value	Defined in
<a id="property-manifest"></a> `manifest`	`readonly`	`object`	`STANDARD_RUNTIME_MANIFEST`	packages/runtime/src/standard-runtime.ts:128
`manifest.id`	`public`	`string`	`undefined`	packages/contracts/dist/runtime.d.ts:9
`manifest.metadata?`	`public`	`JsonObject`	`undefined`	packages/contracts/dist/runtime.d.ts:12
`manifest.protocolVersion`	`public`	`"1"`	`undefined`	packages/contracts/dist/runtime.d.ts:11
`manifest.version`	`public`	`string`	`undefined`	packages/contracts/dist/runtime.d.ts:10

Parameter	Type
`request`	`RuntimeTurnRequest`
`host`	`RuntimeHost`
`signal`	`AbortSignal`

Parameter	Type
`kernel`	`TurnKernel`
`driver`	`AgentTurnDriver`
`options`	`TurnExecutorOptions`

Parameter	Type
`outcome`	`"succeeded"` \| `"denied"` \| `"failed"` \| `"cancelled"` \| `"escalated"`
`signal`	`AbortSignal`

Property	Type	Description	Defined in
<a id="property-onevent"></a> `onEvent?`	(`event`) => `void`	Synchronous observation hook for streaming an immutable event snapshot.	packages/runtime/src/executor.ts:84
<a id="property-signal"></a> `signal?`	`AbortSignal`	-	packages/runtime/src/executor.ts:82

Parameter	Type
`event`	{ `data`: `JsonValue`; `type`: `string`; }
`event.data`	`JsonValue`
`event.type`	`string`

Parameter	Type
`call`	{ `arguments`: `JsonObject`; `id`: `string`; `requestedAt`: `string`; `tool`: `string`; `traceId`: `string`; }
`call.arguments`	`JsonObject`
`call.id?`	`string`
`call.requestedAt?`	`string`
`call.tool?`	`string`
`call.traceId?`	`string`
`options?`	`RuntimeToolInvocationOptions`

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Property	Modifier	Type	Description	Defined in
<a id="property-actor"></a> `actor`	`readonly`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }	-	packages/runtime/src/runtime-plugin.ts:75
<a id="property-namespaceid"></a> `namespaceId`	`readonly`	`string`	-	packages/runtime/src/runtime-plugin.ts:77
<a id="property-now"></a> `now`	`readonly`	`string`	-	packages/runtime/src/runtime-plugin.ts:80
<a id="property-owner"></a> `owner`	`readonly`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }	-	packages/runtime/src/runtime-plugin.ts:76
<a id="property-purpose"></a> `purpose`	`readonly`	`string`	-	packages/runtime/src/runtime-plugin.ts:78
<a id="property-reach"></a> `reach`	`readonly`	{ `reach`: `object`[]; `status`: `"computed"`; } \| { `reasonCode`: `"authority_unavailable"` \| `"usage_store_unavailable"`; `status`: `"unavailable"`; }	Where this turn may operate, with the authority stripped out. The catalogue says which tools exist; this says which resources they are worth pointing at. Without it a runtime can only guess paths and collect denials, or the host reads raw grants to describe the boundary in a prompt -- at exactly the seam designed to keep grants away from the model. `computed` is derived by `SharedOSKernel.reach` from the grants the turn's decisions are made against, then narrowed to the namespaces this turn's catalogue operates on. It carries no grant id, issuer, expiry, or budget, and a bounded grant whose budget is spent does not appear. `unavailable` means the reach could not be established, and `reasonCode` says why: `usage_store_unavailable` when a bounded budget could not be read, or `authority_unavailable` when the authority could not be loaded again after admission. Either is handed over as such rather than as an empty list that would read as "nothing", which is a true answer for some turns and not for this one. The turn still runs: every call is decided on its own, and a call that depends on what could not be read fails closed under the same code. Descriptive, never permissive: every call is authorized independently, so an entry here is not a permission and a stale one cannot open anything.	packages/runtime/src/runtime-plugin.ts:105
<a id="property-traceid"></a> `traceId`	`readonly`	`string`	-	packages/runtime/src/runtime-plugin.ts:79

Property	Type	Description	Defined in
<a id="property-clock"></a> `clock?`	() => `string`	-	packages/runtime/src/executor.ts:52
<a id="property-createid"></a> `createId?`	() => `string`	-	packages/runtime/src/executor.ts:53
<a id="property-defaultmaxsteps"></a> `defaultMaxSteps?`	`number`	-	packages/runtime/src/executor.ts:54
<a id="property-defaultmaxtoolcalls"></a> `defaultMaxToolCalls?`	`number`	-	packages/runtime/src/executor.ts:55
<a id="property-defaulttimeoutms"></a> `defaultTimeoutMs?`	`number`	-	packages/runtime/src/executor.ts:56
<a id="property-onturnerror"></a> `onTurnError?`	`TurnErrorReporter`	Notification for a throw the turn body did not convert into an outcome. The envelope contains such a throw and ends the turn `failed` with `runtime_failed`; the error itself comes here rather than being discarded. See TurnErrorReporter for what it may and may not be used for. Not only the plugin's. The turn body also calls `openTurnAuthority`, `admitTurn`, `reach`, and `listTools`, and a host port that throws arrives here too under the same terminal code. That conflation is in the wire vocabulary and is not fixed by this hook; the error's own stack is what separates them, which is the reason for handing it over rather than classifying it here.	packages/runtime/src/executor.ts:78
<a id="property-spans"></a> `spans?`	`SpanSink`	Where the envelope reports what it cost, when a host is measuring. A second clock, and deliberately not the one `clock` supplies: that one names instants for a record and a conformance run freezes it. See SpanSink.	packages/runtime/src/executor.ts:64

Property	Modifier	Type	Defined in
<a id="property-maxsteps"></a> `maxSteps`	`readonly`	`number`	packages/runtime/src/runtime-plugin.ts:117
<a id="property-maxtoolcalls"></a> `maxToolCalls`	`readonly`	`number`	packages/runtime/src/runtime-plugin.ts:118
<a id="property-timeoutms"></a> `timeoutMs`	`readonly`	`number`	packages/runtime/src/runtime-plugin.ts:119

Property	Modifier	Type	Defined in
<a id="property-manifest-1"></a> `manifest`	`readonly`	`object`	packages/runtime/src/runtime-plugin.ts:150
`manifest.id`	`public`	`string`	packages/contracts/dist/runtime.d.ts:9
`manifest.metadata?`	`public`	`JsonObject`	packages/contracts/dist/runtime.d.ts:12
`manifest.protocolVersion`	`public`	`"1"`	packages/contracts/dist/runtime.d.ts:11
`manifest.version`	`public`	`string`	packages/contracts/dist/runtime.d.ts:10

Property	Type	Description	Defined in
<a id="property-closetimeoutms"></a> `closeTimeoutMs?`	`number`	-	packages/runtime/src/standard-runtime.ts:101
<a id="property-onturnerror-1"></a> `onTurnError?`	`TurnErrorReporter`	Notification for a throw the loop contained rather than propagated. A driver that throws ends the turn `driver_failed`, which is a cooperative outcome the envelope never sees as an exception -- so the executor's own hook cannot report it and this one exists. Same contract either way; see TurnErrorReporter.	packages/runtime/src/standard-runtime.ts:110

Property	Modifier	Type	Defined in
<a id="property-executionid"></a> `executionId`	`readonly`	`string`	packages/runtime/src/runtime-plugin.ts:19
<a id="property-traceid-1"></a> `traceId`	`readonly`	`string`	packages/runtime/src/runtime-plugin.ts:20

Property	Type	Description	Inherited from	Defined in
<a id="property-clock-1"></a> `clock?`	() => `string`	-	`SharedOSExecutorOptions`.`clock`	packages/runtime/src/executor.ts:52
<a id="property-closetimeoutms-1"></a> `closeTimeoutMs?`	`number`	-	`StandardRuntimeOptions`.`closeTimeoutMs`	packages/runtime/src/standard-runtime.ts:101
<a id="property-createid-1"></a> `createId?`	() => `string`	-	`SharedOSExecutorOptions`.`createId`	packages/runtime/src/executor.ts:53
<a id="property-defaultmaxsteps-1"></a> `defaultMaxSteps?`	`number`	-	`SharedOSExecutorOptions`.`defaultMaxSteps`	packages/runtime/src/executor.ts:54
<a id="property-defaultmaxtoolcalls-1"></a> `defaultMaxToolCalls?`	`number`	-	`SharedOSExecutorOptions`.`defaultMaxToolCalls`	packages/runtime/src/executor.ts:55
<a id="property-defaulttimeoutms-1"></a> `defaultTimeoutMs?`	`number`	-	`SharedOSExecutorOptions`.`defaultTimeoutMs`	packages/runtime/src/executor.ts:56
<a id="property-onturnerror-2"></a> `onTurnError?`	`TurnErrorReporter`	Notification for a throw the turn body did not convert into an outcome. The envelope contains such a throw and ends the turn `failed` with `runtime_failed`; the error itself comes here rather than being discarded. See TurnErrorReporter for what it may and may not be used for. Not only the plugin's. The turn body also calls `openTurnAuthority`, `admitTurn`, `reach`, and `listTools`, and a host port that throws arrives here too under the same terminal code. That conflation is in the wire vocabulary and is not fixed by this hook; the error's own stack is what separates them, which is the reason for handing it over rather than classifying it here.	`SharedOSExecutorOptions`.`onTurnError`	packages/runtime/src/executor.ts:78
<a id="property-spans-1"></a> `spans?`	`SpanSink`	Where the envelope reports what it cost, when a host is measuring. A second clock, and deliberately not the one `clock` supplies: that one names instants for a record and a conformance run freezes it. See SpanSink.	`SharedOSExecutorOptions`.`spans`	packages/runtime/src/executor.ts:64

Parameter	Type
`reach`	{ `reach`: `object`[]; `status`: `"computed"`; } \| { `reasonCode`: `"authority_unavailable"` \| `"usage_store_unavailable"`; `status`: `"unavailable"`; }
`options`	`DescribeReachOptions`

Parameter	Type
`reporter`	`TurnErrorReporter` \| `undefined`
`error`	`unknown`
`turn`	`TurnErrorContext`