SharedOS API / @aicoo/sharedos-client
@aicoo/sharedos-client
Runtime-validated HTTP client for a SharedOS service.
npm install @aicoo/sharedos-client@next
import { SharedOSClient } from "@aicoo/sharedos-client";
const client = new SharedOSClient({ baseUrl: "https://sharedos.example" });
const tools = await client.listTools();
const namespaces = await client.listToolNamespaces();
await client.updateToolNamespaces({ enable: ["calendar"] });
Enabling a namespace changes tool availability only. Each returned or invoked tool still requires its declared capability grant.
Options are { baseUrl, token?, fetch?, headers? }. token — a string or an
async function returning one — is sent as authorization: Bearer <token>;
headers, a value or an async function, carries anything else, and token
wins when both name the authorization header. Every method also takes
{ signal?, headers?, purpose? }; purpose is sent as x-sharedos-purpose
for the server's resolveContext to read. Neither header is authority: the
server derives the AccessContext from its own authenticated state, and every
operation still needs a matching grant.
SharedOS is currently an 0.x prerelease.
Classes
SharedOSClient
Defined in: packages/client/src/index.ts:63
Constructors
Constructor
new SharedOSClient(
options):SharedOSClient
Defined in: packages/client/src/index.ts:69
Parameters
| Parameter | Type |
|---|---|
options | SharedOSClientOptions |
Returns
Methods
authorize()
authorize(
request,options?):Promise<{allowed:boolean;matchedGrantId?:string;metadata?:JsonObject;reasonCode:string;requiredAuthority?: {capabilities:object[];constraints?: {delegationDepth?:number;expiresAt?:string;maxUses?:number;notBefore?:string;purposes?:string[]; };id:string;metadata?:JsonObject;namespaceId:string;owner: {kind:"human";userId:string; } | {agentId:string;kind:"agent"; } | {conversationId:string;kind:"group"; } | {kind:"service";serviceId:string; };purpose:string;requestedAt:string;requester: {kind:"human";userId:string; } | {agentId:string;kind:"agent"; } | {conversationId:string;kind:"group"; } | {kind:"service";serviceId:string; }; }; }>
Defined in: packages/client/src/index.ts:80
Parameters
| Parameter | Type |
|---|---|
request | { action: string; resource: { namespace: string; owner?: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; path: string[]; }; } |
request.action | string |
request.resource? | { namespace: string; owner?: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; path: string[]; } |
request.resource.namespace? | string |
request.resource.owner? | { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; } |
request.resource.path? | string[] |
options? | SharedOSCallOptions |
Returns
Promise<{ allowed: boolean; matchedGrantId?: string; metadata?: JsonObject; reasonCode: string; requiredAuthority?: { capabilities: object[]; constraints?: { delegationDepth?: number; expiresAt?: string; maxUses?: number; notBefore?: string; purposes?: string[]; }; id: string; metadata?: JsonObject; namespaceId: string; owner: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; purpose: string; requestedAt: string; requester: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; }; }>
executeTurn()
executeTurn(
request,options?):Promise<{completedAt:string;events:object[];executionId:string;metadata?:JsonObject;output:JsonValue;startedAt:string;status:"succeeded";traceId:string;version:"1"; } | {completedAt:string;error: {code:string;details?:JsonObject;message:string;retryable?:boolean; };events:object[];executionId:string;metadata?:JsonObject;startedAt:string;status:"denied";traceId:string;version:"1"; } | {completedAt:string;error: {code:string;details?:JsonObject;message:string;retryable?:boolean; };events:object[];executionId:string;metadata?:JsonObject;startedAt:string;status:"failed";traceId:string;version:"1"; } | {completedAt:string;error?: {code:string;details?:JsonObject;message:string;retryable?:boolean; };events:object[];executionId:string;metadata?:JsonObject;startedAt:string;status:"cancelled";traceId:string;version:"1"; } | {completedAt:string;escalation: {reason:string;requestedAt:string;requestedAuthority?: {capabilities:object[];constraints?: {delegationDepth?:number;expiresAt?:string;maxUses?:number;notBefore?:string;purposes?:string[]; };id:string;metadata?:JsonObject;namespaceId:string;owner: {kind:"human";userId:string; } | {agentId:string;kind:"agent"; } | {conversationId:string;kind:"group"; } | {kind:"service";serviceId:string; };purpose:string;requestedAt:string;requester: {kind:"human";userId:string; } | {agentId:string;kind:"agent"; } | {conversationId:string;kind:"group"; } | {kind:"service";serviceId:string; }; };reviewer: {kind:"human";userId:string; } | {agentId:string;kind:"agent"; } | {conversationId:string;kind:"group"; } | {kind:"service";serviceId:string; };status:"pending"; };events:object[];executionId:string;metadata?:JsonObject;startedAt:string;status:"escalated";traceId:string;version:"1"; }>
Defined in: packages/client/src/index.ts:151
Parameters
| Parameter | Type |
|---|---|
request | { agent: { agentId: string; kind: "agent"; }; 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; version: "1"; } |
request.agent | { agentId: string; kind: "agent"; } |
request.agent.agentId? | string |
request.agent.kind? | "agent" |
request.executionId? | string |
request.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"; } |
request.message.createdAt? | string |
request.message.id? | string |
request.message.payload? | JsonValue |
request.message.provenance? | { metadata?: JsonObject; parentIds: string[]; source: string; } |
request.message.provenance.metadata? | JsonObject |
request.message.provenance.parentIds? | string[] |
request.message.provenance.source? | string |
request.message.purpose? | string |
request.message.receiver? | { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; } |
request.message.replyTo? | string |
request.message.sender? | { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; } |
request.message.traceId? | string |
request.message.version? | "1" |
request.metadata? | JsonObject |
request.options? | { maxSteps?: number; maxToolCalls?: number; timeoutMs?: number; } |
request.options.maxSteps? | number |
request.options.maxToolCalls? | number |
request.options.timeoutMs? | number |
request.state? | JsonObject |
request.version? | "1" |
options? | SharedOSCallOptions |
Returns
Promise<{ completedAt: string; events: object[]; executionId: string; metadata?: JsonObject; output: JsonValue; startedAt: string; status: "succeeded"; traceId: string; version: "1"; } | { completedAt: string; error: { code: string; details?: JsonObject; message: string; retryable?: boolean; }; events: object[]; executionId: string; metadata?: JsonObject; startedAt: string; status: "denied"; traceId: string; version: "1"; } | { completedAt: string; error: { code: string; details?: JsonObject; message: string; retryable?: boolean; }; events: object[]; executionId: string; metadata?: JsonObject; startedAt: string; status: "failed"; traceId: string; version: "1"; } | { completedAt: string; error?: { code: string; details?: JsonObject; message: string; retryable?: boolean; }; events: object[]; executionId: string; metadata?: JsonObject; startedAt: string; status: "cancelled"; traceId: string; version: "1"; } | { completedAt: string; escalation: { reason: string; requestedAt: string; requestedAuthority?: { capabilities: object[]; constraints?: { delegationDepth?: number; expiresAt?: string; maxUses?: number; notBefore?: string; purposes?: string[]; }; id: string; metadata?: JsonObject; namespaceId: string; owner: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; purpose: string; requestedAt: string; requester: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; }; reviewer: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; status: "pending"; }; events: object[]; executionId: string; metadata?: JsonObject; startedAt: string; status: "escalated"; traceId: string; version: "1"; }>
health()
health(
options?):Promise<{protocolVersion:"1";status:"ok"; }>
Defined in: packages/client/src/index.ts:76
Parameters
| Parameter | Type |
|---|---|
options? | SharedOSCallOptions |
Returns
Promise<{ protocolVersion: "1"; status: "ok"; }>
invokeResource()
invokeResource(
operation,options?):Promise<{completedAt:string;metadata?:JsonObject;operationId:string;output:JsonValue;status:"succeeded"; } | {completedAt:string;error: {code:string;details?:JsonObject;message:string;retryable?:boolean; };metadata?:JsonObject;operationId:string;status:"denied"; } | {completedAt:string;error: {code:string;details?:JsonObject;message:string;retryable?:boolean; };metadata?:JsonObject;operationId:string;status:"failed"; }>
Defined in: packages/client/src/index.ts:132
Parameters
| Parameter | Type |
|---|---|
operation | { action: string; input?: JsonValue; metadata?: JsonObject; operationId: string; resource: { namespace: string; owner?: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; path: string[]; }; } |
operation.action | string |
operation.input? | JsonValue |
operation.metadata? | JsonObject |
operation.operationId? | string |
operation.resource? | { namespace: string; owner?: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; path: string[]; } |
operation.resource.namespace? | string |
operation.resource.owner? | { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; } |
operation.resource.path? | string[] |
options? | SharedOSCallOptions |
Returns
Promise<{ completedAt: string; metadata?: JsonObject; operationId: string; output: JsonValue; status: "succeeded"; } | { completedAt: string; error: { code: string; details?: JsonObject; message: string; retryable?: boolean; }; metadata?: JsonObject; operationId: string; status: "denied"; } | { completedAt: string; error: { code: string; details?: JsonObject; message: string; retryable?: boolean; }; metadata?: JsonObject; operationId: string; status: "failed"; }>
invokeTool()
invokeTool(
call,options?):Promise<{callId:string;completedAt:string;metadata?:JsonObject;output:JsonValue;status:"succeeded";tool:string; } | {callId:string;completedAt:string;error: {code:string;details?:JsonObject;message:string;retryable?:boolean; };metadata?:JsonObject;status:"denied";tool:string; } | {callId:string;completedAt:string;error: {code:string;details?:JsonObject;message:string;retryable?:boolean; };metadata?:JsonObject;status:"failed";tool:string; }>
Defined in: packages/client/src/index.ts:128
Parameters
| 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? | SharedOSCallOptions |
Returns
Promise<{ callId: string; completedAt: string; metadata?: JsonObject; output: JsonValue; status: "succeeded"; tool: string; } | { callId: string; completedAt: string; error: { code: string; details?: JsonObject; message: string; retryable?: boolean; }; metadata?: JsonObject; status: "denied"; tool: string; } | { callId: string; completedAt: string; error: { code: string; details?: JsonObject; message: string; retryable?: boolean; }; metadata?: JsonObject; status: "failed"; tool: string; }>
listToolNamespaces()
listToolNamespaces(
options?):Promise<{namespaces:object[];summary: {disabled:number;enabled:number;total:number; }; }>
Defined in: packages/client/src/index.ts:106
Parameters
| Parameter | Type |
|---|---|
options? | SharedOSCallOptions |
Returns
Promise<{ namespaces: object[]; summary: { disabled: number; enabled: number; total: number; }; }>
listTools()
listTools(
options?):Promise<readonlyobject[]>
Defined in: packages/client/src/index.ts:87
Parameters
| Parameter | Type |
|---|---|
options? | SharedOSCallOptions |
Returns
Promise<readonly object[]>
reach()
reach(
options?):Promise<{reach:object[];status:"computed"; } | {reasonCode:"authority_unavailable"|"usage_store_unavailable";status:"unavailable"; }>
Defined in: packages/client/src/index.ts:102
Where this caller may operate, with the authority stripped out.
Grant reach for the context the server resolved, as SharedOSKernel.reach
answers it: where some call would be authorized, not that any call will be.
It is not narrowed to the tool catalogue, because invokeResource is not
gated by tool namespaces; a client driving a model from listTools()
keeps the entries whose namespace one of those tools operates on, which is
what the execution envelope does for a turn. unavailable is an answer
rather than an error: nothing could be established, and the code says why.
Parameters
| Parameter | Type |
|---|---|
options? | SharedOSCallOptions |
Returns
Promise<{ reach: object[]; status: "computed"; } | { reasonCode: "authority_unavailable" | "usage_store_unavailable"; status: "unavailable"; }>
sendMessage()
sendMessage(
envelope,options?):Promise<{messageId:string;metadata?:JsonObject;status:"accepted";timestamp:string; } | {messageId:string;metadata?:JsonObject;status:"delivered";timestamp:string; } | {error: {code:string;details?:JsonObject;message:string;retryable?:boolean; };messageId:string;metadata?:JsonObject;status:"denied";timestamp:string; } | {error: {code:string;details?:JsonObject;message:string;retryable?:boolean; };messageId:string;metadata?:JsonObject;status:"failed";timestamp:string; }>
Defined in: packages/client/src/index.ts:144
Parameters
| Parameter | Type |
|---|---|
envelope | { 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"; } |
envelope.createdAt | string |
envelope.id? | string |
envelope.payload? | JsonValue |
envelope.provenance? | { metadata?: JsonObject; parentIds: string[]; source: string; } |
envelope.provenance.metadata? | JsonObject |
envelope.provenance.parentIds? | string[] |
envelope.provenance.source? | string |
envelope.purpose? | string |
envelope.receiver? | { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; } |
envelope.replyTo? | string |
envelope.sender? | { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; } |
envelope.traceId? | string |
envelope.version? | "1" |
options? | SharedOSCallOptions |
Returns
Promise<{ messageId: string; metadata?: JsonObject; status: "accepted"; timestamp: string; } | { messageId: string; metadata?: JsonObject; status: "delivered"; timestamp: string; } | { error: { code: string; details?: JsonObject; message: string; retryable?: boolean; }; messageId: string; metadata?: JsonObject; status: "denied"; timestamp: string; } | { error: { code: string; details?: JsonObject; message: string; retryable?: boolean; }; messageId: string; metadata?: JsonObject; status: "failed"; timestamp: string; }>
updateToolNamespaces()
updateToolNamespaces(
update,options?):Promise<{namespaces:object[];summary: {disabled:number;enabled:number;total:number; }; }>
Defined in: packages/client/src/index.ts:115
Parameters
| Parameter | Type |
|---|---|
update | { disable?: string[]; enable?: string[]; } |
update.disable? | string[] |
update.enable? | string[] |
options? | SharedOSCallOptions |
Returns
Promise<{ namespaces: object[]; summary: { disabled: number; enabled: number; total: number; }; }>
SharedOSClientError
Defined in: packages/client/src/index.ts:49
Extends
Error
Constructors
Constructor
new SharedOSClientError(
args):SharedOSClientError
Defined in: packages/client/src/index.ts:54
Parameters
| Parameter | Type |
|---|---|
args | { code: string; message: string; requestId?: string; status: number; } |
args.code | string |
args.message | string |
args.requestId? | string |
args.status | number |
Returns
Overrides
Error.constructor
Properties
| 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-code"></a> code | readonly | string | - | - | packages/client/src/index.ts:51 |
<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-requestid"></a> requestId | readonly | string | undefined | - | - | packages/client/src/index.ts:52 |
<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-status"></a> status | readonly | number | - | - | packages/client/src/index.ts:50 |
<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 |
Methods
captureStackTrace()
staticcaptureStackTrace(targetObject,constructorOpt?):void
Defined in: node_modules/.pnpm/@types+node@22.20.1/node_modules/@types/node/globals.d.ts:52
Creates a .stack property on targetObject, which when accessed returns
a string representing the location in the code at which
Error.captureStackTrace() was called.
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack; // Similar to `new Error().stack`
The first line of the trace will be prefixed with
${myObject.name}: ${myObject.message}.
The optional constructorOpt argument accepts a function. If given, all frames
above constructorOpt, including constructorOpt, will be omitted from the
generated stack trace.
The constructorOpt argument is useful for hiding implementation
details of error generation from the user. For instance:
function a() {
b();
}
function b() {
c();
}
function c() {
// Create an error without stack trace to avoid calculating the stack trace twice.
const { stackTraceLimit } = Error;
Error.stackTraceLimit = 0;
const error = new Error();
Error.stackTraceLimit = stackTraceLimit;
// Capture the stack trace above function b
Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
throw error;
}
a();
Parameters
| Parameter | Type |
|---|---|
targetObject | object |
constructorOpt? | Function |
Returns
void
Inherited from
Error.captureStackTrace
prepareStackTrace()
staticprepareStackTrace(err,stackTraces):any
Defined in: node_modules/.pnpm/@types+node@22.20.1/node_modules/@types/node/globals.d.ts:56
Parameters
| Parameter | Type |
|---|---|
err | Error |
stackTraces | CallSite[] |
Returns
any
See
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
Inherited from
Error.prepareStackTrace
Interfaces
SharedOSCallOptions
Defined in: packages/client/src/index.ts:41
Properties
| Property | Type | Defined in |
|---|---|---|
<a id="property-headers"></a> headers? | HeadersInit | packages/client/src/index.ts:44 |
<a id="property-purpose"></a> purpose? | string | packages/client/src/index.ts:42 |
<a id="property-signal"></a> signal? | AbortSignal | packages/client/src/index.ts:43 |
SharedOSClientOptions
Defined in: packages/client/src/index.ts:34
Properties
| Property | Type | Defined in |
|---|---|---|
<a id="property-baseurl"></a> baseUrl | string | packages/client/src/index.ts:35 |
<a id="property-fetch"></a> fetch? | {(input, init?): Promise<Response>; (input, init?): Promise<Response>; } | packages/client/src/index.ts:37 |
<a id="property-headers-1"></a> headers? | HeadersInit | (() => HeadersInit | Promise<HeadersInit>) | packages/client/src/index.ts:38 |
<a id="property-token"></a> token? | string | (() => string | Promise<string>) | packages/client/src/index.ts:36 |
Type Aliases
RemoteExecutionRequest
RemoteExecutionRequest =
z.infer<typeofRemoteExecutionRequestSchema>>
Defined in: packages/contracts/dist/http.d.ts:1128
RemoteResourceOperation
RemoteResourceOperation =
z.infer<typeofRemoteResourceOperationSchema>>
Defined in: packages/contracts/dist/http.d.ts:334
SharedOSHealth
SharedOSHealth =
z.infer<typeofSharedOSHealthSchema>>
Defined in: packages/contracts/dist/http.d.ts:1139