SharedOS API / @aicoo/sharedos-testkit

@aicoo/sharedos-testkit

Deterministic in-memory fixtures and recording providers for SharedOS tests.

npm install --save-dev @aicoo/sharedos-testkit@next

This package is for tests, examples, and isolated experimental worlds. Its in-memory stores are not durable or multi-instance-safe production storage. InMemoryToolNamespaceSettingsStore can exercise the namespace control plane without becoming a production settings backend.

SharedOS is currently an 0.x prerelease.

Classes

InMemoryAuditSink

Defined in: testkit/src/index.ts:26

Implements

AuditSink

Constructors

Constructor

new InMemoryAuditSink(): InMemoryAuditSink

Returns

InMemoryAuditSink

Properties

Property	Modifier	Type	Default value	Defined in
<a id="property-events"></a> `events`	`readonly`	`AuditEvent`[]	`[]`	testkit/src/index.ts:27

Methods

record()

record(event): Promise<void>>

Defined in: testkit/src/index.ts:29

Parameters

Parameter	Type
`event`	`AuditEvent`

Returns

Promise<void>

Constructors

Constructor

new InMemoryMessageTransport(): InMemoryMessageTransport

Returns

InMemoryMessageTransport

Properties

Property	Modifier	Type	Default value	Defined in
<a id="property-deliveries"></a> `deliveries`	`readonly`	`object`[]	`[]`	testkit/src/index.ts:35

Methods

deliver()

deliver(context, envelope): 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: testkit/src/index.ts:37

Parameters

Parameter	Type
`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`; }
`context.actor`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }
`context.authority`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }
`context.enabledToolNamespaces`	`string`[]
`context.grants`	`object`[]
`context.namespaceId`	`string`
`context.now`	`string`
`context.owner`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }
`context.purpose`	`string`
`context.traceId`	`string`
`envelope`	{ `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"`; }
`envelope.createdAt`	`string`
`envelope.id`	`string`
`envelope.intent`	`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"`

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; }>

Implementation of

MessageTransport.deliver

InMemoryResourceProvider

Defined in: testkit/src/index.ts:80

A host-neutral recording provider for examples, conformance tests, and isolated experiment worlds.

Implements

ResourceProvider

Constructors

Constructor

new InMemoryResourceProvider(namespace, handler?): InMemoryResourceProvider

Defined in: testkit/src/index.ts:85

Parameters

Parameter	Type	Default value
`namespace`	`string`	`undefined`
`handler`	`ResourceHandler`	`echoResourceOperation`

Returns

InMemoryResourceProvider

Properties

Property	Modifier	Type	Default value	Defined in
<a id="property-namespace"></a> `namespace`	`readonly`	`string`	`undefined`	testkit/src/index.ts:81
<a id="property-operations"></a> `operations`	`readonly`	`object`[]	`[]`	testkit/src/index.ts:82

Methods

invoke()

invoke(operation): 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: testkit/src/index.ts:90

Parameters

Parameter	Type
`operation`	{ `action`: `string`; `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?`: `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.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`; }
`operation.context.actor`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }
`operation.context.authority`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }
`operation.context.enabledToolNamespaces`	`string`[]
`operation.context.grants`	`object`[]
`operation.context.namespaceId`	`string`
`operation.context.now`	`string`
`operation.context.owner`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }
`operation.context.purpose`	`string`
`operation.context.traceId`	`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`[]

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"; }>

ToolNamespaceSettingsStore

Constructors

Constructor

new InMemoryToolNamespaceSettingsStore(initial?): InMemoryToolNamespaceSettingsStore

Defined in: testkit/src/index.ts:54

Parameters

Parameter	Type
`initial`	`Readonly`<`Record`<`string`, readonly `ToolNamespace`[]>>

applyUpdate(context, update): Promise<readonly string[]>

Defined in: testkit/src/index.ts:60

Parameters

Parameter	Type
`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`; }
`context.actor`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }
`context.authority`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }
`context.enabledToolNamespaces`	`string`[]
`context.grants`	`object`[]
`context.namespaceId`	`string`
`context.now`	`string`
`context.owner`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }
`context.purpose`	`string`
`context.traceId`	`string`
`update`	{ `disable?`: `string`[]; `enable?`: `string`[]; }
`update.disable?`	`string`[]
`update.enable?`	`string`[]

get(namespaceId): readonly string[]

Defined in: testkit/src/index.ts:72

Parameters

Parameter	Type
`namespaceId`	`string`

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`; }	testkit/src/index.ts:117
<a id="property-authority"></a> `authority?`	`readonly`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }	testkit/src/index.ts:118
<a id="property-enabledtoolnamespaces"></a> `enabledToolNamespaces?`	`readonly`	readonly `string`[]	testkit/src/index.ts:121
<a id="property-grants"></a> `grants?`	`readonly`	readonly `object`[]	testkit/src/index.ts:124
<a id="property-namespaceid"></a> `namespaceId?`	`readonly`	`string`	testkit/src/index.ts:120
<a id="property-now"></a> `now?`	`readonly`	`string`	testkit/src/index.ts:125
<a id="property-owner"></a> `owner?`	`readonly`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }	testkit/src/index.ts:119
<a id="property-purpose"></a> `purpose?`	`readonly`	`string`	testkit/src/index.ts:122
<a id="property-traceid"></a> `traceId?`	`readonly`	`string`	testkit/src/index.ts:123

TestGrantOptions

Defined in: testkit/src/index.ts:143

Properties

Property	Modifier	Type	Defined in
<a id="property-capabilities"></a> `capabilities`	`readonly`	readonly `object`[]	testkit/src/index.ts:148
<a id="property-expiresat"></a> `expiresAt?`	`readonly`	`string`	testkit/src/index.ts:151
<a id="property-id"></a> `id?`	`readonly`	`string`	testkit/src/index.ts:144
<a id="property-issuedat"></a> `issuedAt?`	`readonly`	`string`	testkit/src/index.ts:150
<a id="property-issuer"></a> `issuer?`	`readonly`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }	testkit/src/index.ts:147
<a id="property-namespaceid-1"></a> `namespaceId?`	`readonly`	`string`	testkit/src/index.ts:145
<a id="property-purposes"></a> `purposes?`	`readonly`	readonly `string`[]	testkit/src/index.ts:149
<a id="property-subject"></a> `subject?`	`readonly`	{ `kind`: `"human"`; `userId`: `string`; } \| { `agentId`: `string`; `kind`: `"agent"`; } \| { `conversationId`: `string`; `kind`: `"group"`; } \| { `kind`: `"service"`; `serviceId`: `string`; }	testkit/src/index.ts:146

TestKernel

Defined in: testkit/src/index.ts:96

Properties

Property	Modifier	Type	Defined in
<a id="property-audit"></a> `audit`	`readonly`	`InMemoryAuditSink`	testkit/src/index.ts:98
<a id="property-kernel"></a> `kernel`	`readonly`	`SharedOSKernel`	testkit/src/index.ts:97
<a id="property-messages"></a> `messages`	`readonly`	`InMemoryMessageTransport`	testkit/src/index.ts:99

Type Aliases

ResourceHandler

ResourceHandler = (operation) => Promise<ResourceResult>>

Defined in: testkit/src/index.ts:77

Parameters

Parameter	Type
`operation`	`ResourceOperation`

createTestContext(options?): object

Defined in: testkit/src/index.ts:128

Parameters

Parameter	Type
`options`	`TestContextOptions`

Returns

object

actor

actor: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }

authority

authority: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }

enabledToolNamespaces

enabledToolNamespaces: string[]

grants

grants: object[]

namespaceId

namespaceId: string

now

now: string

owner

owner: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }

purpose

purpose: string

traceId

traceId: string

createTestGrant()

createTestGrant(options): object

Defined in: testkit/src/index.ts:154

Parameters

Parameter	Type
`options`	`TestGrantOptions`

Returns

object

capabilities

capabilities: object[]

constraints

constraints: object

constraints.delegationDepth?

optional delegationDepth?: number

constraints.expiresAt?

optional expiresAt?: string

constraints.maxUses?

optional maxUses?: number

constraints.notBefore?

optional notBefore?: string

constraints.purposes?

optional purposes?: string[]

id

id: string

issuedAt

issuedAt: string

issuer

issuer: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }

metadata?

optional metadata?: JsonObject

namespaceId

namespaceId: string

revokedAt?

optional revokedAt?: string

subject

subject: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }

createTestKernel()

createTestKernel(): TestKernel

Defined in: testkit/src/index.ts:102

Returns

TestKernel