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

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. createStandardRuntime is the included one: the standard loop, with one AgentTurnDriver seated.

Standard runtime

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

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

const result = await turns.execute(executionRequest);

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; the standard loop 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.
annotate, which states one fact about the turn for its record. The envelope writes it into the result's metadata on every ending, a cancelled turn included, and it never refuses on the state of the host (ADR 0007).

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([
  createStandardRuntime({ driver: 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 a 1.0.0 preview.

Classes

RuntimeNotFoundError

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

Extends

Error

Constructors

Constructor

new RuntimeNotFoundError(runtimeId): RuntimeNotFoundError

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

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	Description	Defined in
<a id="property-manifest"></a> `manifest?`	`readonly`	`object`	Who this driver is, for the record. The executor stamps the plugin's manifest on every execution record, and the loop is the same whichever driver is seated, so the loop reports the seated driver's manifest as its own: evidence is filed under what produced it. A driver that states none is reported as `sharedos.standard`.	packages/runtime/src/standard-runtime.ts:127
`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

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:105
<a id="property-signal"></a> `signal?`	`AbortSignal`	-	packages/runtime/src/executor.ts:103

Property	Modifier	Type	Description	Defined in
<a id="property-draining"></a> `draining?`	`readonly`	`AbortSignal`	Aborted once the turn takes nothing new: `drainGraceMs` ahead of its deadline, or when the envelope is ending it on an audit outage. From then a new `invokeTool` comes back `denied` with `turn_draining`, and a call already with the kernel still answers with its real result. A plugin that reads this stops asking its model for decisions, which is what the standard loop does. One that does not read it is refused the same calls and stopped at the deadline. It is also aborted whenever the turn's own signal is. Optional so a narrow host double stays viable; the envelope always supplies it.	packages/runtime/src/runtime-plugin.ts:160
<a id="property-limits"></a> `limits`	`readonly`	`RuntimeLimits`	-	packages/runtime/src/runtime-plugin.ts:147

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`

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

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

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

Property	Type	Description	Defined in
<a id="property-clock"></a> `clock?`	() => `string`	-	packages/runtime/src/executor.ts:57
<a id="property-createid"></a> `createId?`	() => `string`	-	packages/runtime/src/executor.ts:58
<a id="property-defaultmaxsteps"></a> `defaultMaxSteps?`	`number`	-	packages/runtime/src/executor.ts:59
<a id="property-defaultmaxtoolcalls"></a> `defaultMaxToolCalls?`	`number`	-	packages/runtime/src/executor.ts:60
<a id="property-defaulttimeoutms"></a> `defaultTimeoutMs?`	`number`	-	packages/runtime/src/executor.ts:61
<a id="property-draingracems"></a> `drainGraceMs?`	`number`	How long before a turn's deadline it stops taking new tool calls, so the calls already inside a handler can answer before the deadline stops them. Inside the limit, never on top of it: with `timeoutMs` 120 000 and a grace of 5 000 a new call is refused from 115 s, a handler running then is left alone, and the abort reaches it at 120 s as it always did. A handler still running at the deadline is recorded `interrupted`. An audit outage drains the same way, for the grace or the time left, whichever is shorter. A host's own cancellation does not: it stops the turn at once, as before. Zero, the default, is the behaviour before this option. It is not capped against a request's `timeoutMs`; a grace no smaller than the limit leaves a turn no time in which a call is taken, and choosing it is the host's.	packages/runtime/src/executor.ts:77
<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:99
<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:85

Property	Type	Description	Defined in
<a id="property-closetimeoutms"></a> `closeTimeoutMs?`	`number`	-	packages/runtime/src/standard-runtime.ts:143
<a id="property-driver"></a> `driver`	`AgentTurnDriver`	The one driver this runtime seats.	packages/runtime/src/standard-runtime.ts:142
<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; see TurnErrorReporter.	packages/runtime/src/standard-runtime.ts:152

Property	Modifier	Type	Defined in
<a id="property-manifest-1"></a> `manifest`	`readonly`	`object`	packages/runtime/src/runtime-plugin.ts:201
`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

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

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:83
<a id="property-namespaceid"></a> `namespaceId`	`readonly`	`string`	-	packages/runtime/src/runtime-plugin.ts:85
<a id="property-now"></a> `now`	`readonly`	`string`	-	packages/runtime/src/runtime-plugin.ts:88
<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:84
<a id="property-purpose"></a> `purpose`	`readonly`	`string`	-	packages/runtime/src/runtime-plugin.ts:86
<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:113
<a id="property-traceid"></a> `traceId`	`readonly`	`string`	-	packages/runtime/src/runtime-plugin.ts:87

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

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`