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:

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

const turns = new TurnExecutor(kernel, agentDriver);

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:66

Extends

Error

Constructors

Constructor

new RuntimeNotFoundError(runtimeId): RuntimeNotFoundError

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

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`[]; `grants`: `object`[]; `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`; `intent`: `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`[]; `grants`: `object`[]; `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.grants`	`object`[]
`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`; `intent`: `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.intent`	`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:67
`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"`
`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:51
<a id="property-signal"></a> `signal?`	`AbortSignal`	-	packages/runtime/src/executor.ts:49

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	Type	Defined in
<a id="property-clock"></a> `clock?`	() => `string`	packages/runtime/src/executor.ts:41
<a id="property-createid"></a> `createId?`	() => `string`	packages/runtime/src/executor.ts:42
<a id="property-defaultmaxsteps"></a> `defaultMaxSteps?`	`number`	packages/runtime/src/executor.ts:43
<a id="property-defaultmaxtoolcalls"></a> `defaultMaxToolCalls?`	`number`	packages/runtime/src/executor.ts:44
<a id="property-defaulttimeoutms"></a> `defaultTimeoutMs?`	`number`	packages/runtime/src/executor.ts:45

Property	Type	Inherited from	Defined in
<a id="property-clock-1"></a> `clock?`	() => `string`	`SharedOSExecutorOptions`.`clock`	packages/runtime/src/executor.ts:41
<a id="property-closetimeoutms-1"></a> `closeTimeoutMs?`	`number`	`StandardRuntimeOptions`.`closeTimeoutMs`	packages/runtime/src/standard-runtime.ts:49
<a id="property-createid-1"></a> `createId?`	() => `string`	`SharedOSExecutorOptions`.`createId`	packages/runtime/src/executor.ts:42
<a id="property-defaultmaxsteps-1"></a> `defaultMaxSteps?`	`number`	`SharedOSExecutorOptions`.`defaultMaxSteps`	packages/runtime/src/executor.ts:43
<a id="property-defaultmaxtoolcalls-1"></a> `defaultMaxToolCalls?`	`number`	`SharedOSExecutorOptions`.`defaultMaxToolCalls`	packages/runtime/src/executor.ts:44
<a id="property-defaulttimeoutms-1"></a> `defaultTimeoutMs?`	`number`	`SharedOSExecutorOptions`.`defaultTimeoutMs`	packages/runtime/src/executor.ts:45

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

Property	Modifier	Type	Defined in
<a id="property-manifest-1"></a> `manifest`	`readonly`	`object`	packages/runtime/src/runtime-plugin.ts:58
`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	Modifier	Type	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:15
<a id="property-namespaceid"></a> `namespaceId`	`readonly`	`string`	packages/runtime/src/runtime-plugin.ts:17
<a id="property-now"></a> `now`	`readonly`	`string`	packages/runtime/src/runtime-plugin.ts:20
<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:16
<a id="property-purpose"></a> `purpose`	`readonly`	`string`	packages/runtime/src/runtime-plugin.ts:18
<a id="property-traceid"></a> `traceId`	`readonly`	`string`	packages/runtime/src/runtime-plugin.ts:19