SharedOS API v1.0.0-preview

---

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

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.

A store that is down is a stand-in too: UnavailableGrantSource, UnavailableDelegationChainResolver and UnavailableGrantUsageStore fail every call, so a test can show a decision failing closed. revoke and expire on the two grant stores edit a grant in place, the way a host store would, and throw on an id the store does not hold.

SharedOS is currently a 1.0.0 preview.

Classes

InMemoryAuditSink

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

Implements

• AuditSink

Constructors

Constructor

new InMemoryAuditSink(): InMemoryAuditSink

Returns

InMemoryAuditSink

Properties

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

Methods

record()

record(event): Promise<void>>

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

Parameters

Parameter	Type
event	{ action?: string; actor: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; at: string; authority: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; authorityHash?: string; cause?: string; consumed?: boolean; endedBy?: "envelope" | "runtime"; failClosed?: boolean; grantId?: string; id: string; messageId?: string; metadata?: JsonObject; namespaceId: string; operationId?: string; outcome: "denied" | "failed" | "succeeded" | "allowed" | "escalated" | "interrupted"; owner: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; purpose: string; reason?: string; receiver?: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: 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; }; }; resource?: { namespace: string; owner?: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; path: string[]; }; source?: "envelope" | "kernel"; tool?: string; traceId: string; type: "authorization.checked" | "authority.resolved" | "escalation.requested" | "escalation.auto_decided" | "resource.invoked" | "tool.catalog.listed" | "tool.namespace.catalog.listed" | "tool.namespace.selection.updated" | "tool.invoked" | "message.sent" | "turn.ended"; version: "1"; }
event.action?	string
event.actor	{ kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }
event.at	string
event.authority	{ kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }
event.authorityHash?	string
event.cause?	string
event.consumed?	boolean
event.endedBy?	"envelope" | "runtime"
event.failClosed?	boolean
event.grantId?	string
event.id	string
event.messageId?	string
event.metadata?	JsonObject
event.namespaceId	string
event.operationId?	string
event.outcome	"denied" | "failed" | "succeeded" | "allowed" | "escalated" | "interrupted"
event.owner	{ kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }
event.purpose	string
event.reason?	string
event.receiver?	{ kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }
event.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; }; }
event.requestedAuthority.capabilities	object[]
event.requestedAuthority.constraints?	{ delegationDepth?: number; expiresAt?: string; maxUses?: number; notBefore?: string; purposes?: string[]; }
event.requestedAuthority.constraints.delegationDepth?	number
event.requestedAuthority.constraints.expiresAt?	string
event.requestedAuthority.constraints.maxUses?	number
event.requestedAuthority.constraints.notBefore?	string
event.requestedAuthority.constraints.purposes?	string[]
event.requestedAuthority.id	string
event.requestedAuthority.metadata?	JsonObject
event.requestedAuthority.namespaceId	string
event.requestedAuthority.owner	{ kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }
event.requestedAuthority.purpose	string
event.requestedAuthority.requestedAt	string
event.requestedAuthority.requester	{ kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }
event.resource?	{ namespace: string; owner?: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; path: string[]; }
event.resource.namespace	string
event.resource.owner?	{ kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }
event.resource.path	string[]
event.source?	"envelope" | "kernel"
event.tool?	string
event.traceId	string
event.type	"authorization.checked" | "authority.resolved" | "escalation.requested" | "escalation.auto_decided" | "resource.invoked" | "tool.catalog.listed" | "tool.namespace.catalog.listed" | "tool.namespace.selection.updated" | "tool.invoked" | "message.sent" | "turn.ended"
event.version	"1"

Returns

Promise<void>

Implementation of

AuditSink.record

---

InMemoryDelegationChainResolver

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

Namespace-scoped ancestor lookup for delegated-grant fixtures.

Implements

• DelegationChainResolver

Constructors

Constructor

new InMemoryDelegationChainResolver(grants?): InMemoryDelegationChainResolver

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

Parameters

Parameter	Type	Default value
grants	readonly object[]	[]

Returns

InMemoryDelegationChainResolver

Methods

add()

add(grant): this

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

Parameters

Parameter	Type
grant	{ capabilities: object[]; constraints: { delegationDepth?: number; expiresAt?: string; maxUses?: number; notBefore?: string; purposes?: string[]; }; id: string; issuedAt: string; issuer: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; metadata?: JsonObject; namespaceId: string; parentGrantId?: string; revokedAt?: string; subject: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; }
grant.capabilities	object[]
grant.constraints	{ delegationDepth?: number; expiresAt?: string; maxUses?: number; notBefore?: string; purposes?: string[]; }
grant.constraints.delegationDepth?	number
grant.constraints.expiresAt?	string
grant.constraints.maxUses?	number
grant.constraints.notBefore?	string
grant.constraints.purposes?	string[]
grant.id	string
grant.issuedAt	string
grant.issuer	{ kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }
grant.metadata?	JsonObject
grant.namespaceId	string
grant.parentGrantId?	string
grant.revokedAt?	string
grant.subject	{ kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }

Returns

this

expire()

expire(namespaceId, grantId, expiresAt): this

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

Move a grant's expiry in place, as InMemoryGrantSource.expire does.

Parameters

Parameter	Type
namespaceId	string
grantId	string
expiresAt	string

Returns

this

resolve()

resolve(namespaceId, grantId): Promise<{ capabilities: object[]; constraints: { delegationDepth?: number; expiresAt?: string; maxUses?: number; notBefore?: string; purposes?: string[]; }; id: string; issuedAt: string; issuer: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; metadata?: JsonObject; namespaceId: string; parentGrantId?: string; revokedAt?: string; subject: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; } | undefined>>

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

Parameters

Parameter	Type
namespaceId	string
grantId	string

Returns

Promise<{ capabilities: object[]; constraints: { delegationDepth?: number; expiresAt?: string; maxUses?: number; notBefore?: string; purposes?: string[]; }; id: string; issuedAt: string; issuer: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; metadata?: JsonObject; namespaceId: string; parentGrantId?: string; revokedAt?: string; subject: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; } | undefined>

Implementation of

DelegationChainResolver.resolve

revoke()

revoke(namespaceId, grantId, revokedAt): this

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

Record a revocation the way a host grant store would, in place.

Parameters

Parameter	Type
namespaceId	string
grantId	string
revokedAt	string

Returns

this

---

InMemoryGrantSource

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

A host grant store fixture.

load answers only with grants issued to the context's actor by its authority inside its namespace, which is the contract every production GrantSource must satisfy.

Implements

• GrantSource

Constructors

Constructor

new InMemoryGrantSource(grants?): InMemoryGrantSource

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

Parameters

Parameter	Type	Default value
grants	readonly object[]	[]

Returns

InMemoryGrantSource

Methods

add()

add(...grants): this

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

Parameters

Parameter	Type
...grants	readonly object[]

Returns

this

expire()

expire(grantId, expiresAt): this

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

Move a grant's expiry, the way a host store would record a shortened window.

Parameters

Parameter	Type
grantId	string
expiresAt	string

Returns

this

load()

load(context): Promise<readonly object[]>

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

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[]; 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.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

Returns

Promise<readonly object[]>

Implementation of

GrantSource.load

revoke()

revoke(grantId, revokedAt): this

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

Record a revocation the way a host store would, without deleting history.

Parameters

Parameter	Type
grantId	string
revokedAt	string

Returns

this

---

InMemoryMessageRequestRouter

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

Answers a request from the transport's own log of accepted deliveries.

The reply is derived from the request, so a test can predict it: the id is the request's with -reply appended, the parties are swapped, and the payload names the message it answers. A request the transport never accepted has no reply to give, and asking for one throws.

Implements

• MessageRequestRouter

Constructors

Constructor

new InMemoryMessageRequestRouter(transport): InMemoryMessageRequestRouter

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

Parameters

Parameter	Type
transport	InMemoryMessageTransport

Returns

InMemoryMessageRequestRouter

Methods

resolveReply()

resolveReply(context, request, delivery): Promise<{ 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"; }>

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

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[]; 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.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
request	{ 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.createdAt	string
request.id	string
request.payload	JsonValue
request.provenance?	{ metadata?: JsonObject; parentIds: string[]; source: string; }
request.provenance.metadata?	JsonObject
request.provenance.parentIds	string[]
request.provenance.source	string
request.purpose	string
request.receiver	{ kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }
request.replyTo?	string
request.sender	{ kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }
request.traceId	string
request.version	"1"
delivery	{ 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; }

Returns

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

Implementation of

MessageRequestRouter.resolveReply

---

InMemoryMessageTransport

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

Implements

• MessageTransport

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

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

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[]; 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.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; 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"

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

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

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:271
<a id="property-operations"></a> operations	readonly	object[]	[]	testkit/src/index.ts:272

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

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[]; 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[]; 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.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"; }>

Implementation of

ResourceProvider.invoke

---

InMemoryToolNamespaceSettingsStore

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

Namespace settings fixture keyed by the access-context namespace/world.

Implements

• ToolNamespaceSettingsStore

Constructors

Constructor

new InMemoryToolNamespaceSettingsStore(initial?): InMemoryToolNamespaceSettingsStore

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

Parameters

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

Returns

InMemoryToolNamespaceSettingsStore

Methods

applyUpdate()

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

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

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[]; 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.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[]

Returns

Promise<readonly string[]>

Implementation of

ToolNamespaceSettingsStore.applyUpdate

get()

get(namespaceId): readonly string[]

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

Parameters

Parameter	Type
namespaceId	string

Returns

readonly string[]

---

UnavailableDelegationChainResolver

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

A resolver whose authoritative source is down; every lookup must fail closed.

Implements

• DelegationChainResolver

Constructors

Constructor

new UnavailableDelegationChainResolver(): UnavailableDelegationChainResolver

Returns

UnavailableDelegationChainResolver

Methods

resolve()

resolve(): Promise<{ capabilities: object[]; constraints: { delegationDepth?: number; expiresAt?: string; maxUses?: number; notBefore?: string; purposes?: string[]; }; id: string; issuedAt: string; issuer: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; metadata?: JsonObject; namespaceId: string; parentGrantId?: string; revokedAt?: string; subject: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; } | undefined>>

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

Returns

Promise<{ capabilities: object[]; constraints: { delegationDepth?: number; expiresAt?: string; maxUses?: number; notBefore?: string; purposes?: string[]; }; id: string; issuedAt: string; issuer: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; metadata?: JsonObject; namespaceId: string; parentGrantId?: string; revokedAt?: string; subject: { kind: "human"; userId: string; } | { agentId: string; kind: "agent"; } | { conversationId: string; kind: "group"; } | { kind: "service"; serviceId: string; }; } | undefined>

Implementation of

DelegationChainResolver.resolve

---

UnavailableGrantSource

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

A grant store that is down; every decision made against it must fail closed.

Implements

• GrantSource

Constructors

Constructor

new UnavailableGrantSource(): UnavailableGrantSource

Returns

UnavailableGrantSource

Methods

load()

load(): Promise<readonly object[]>

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

Returns

Promise<readonly object[]>

Implementation of

GrantSource.load

---

UnavailableGrantUsageStore

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

A usage store that cannot answer.

Bounded use is the one authorization question SharedOS cannot decide from the grant set alone, so an unreachable counter is an unknown fact rather than a policy outcome. It throws on both reads and writes: a store that answered reads while failing writes would let discovery quietly disagree with execution.

Implements

• GrantUsageStore

Constructors

Constructor

new UnavailableGrantUsageStore(): UnavailableGrantUsageStore

Returns

UnavailableGrantUsageStore

Methods

getUsage()

getUsage(): Promise<number>>

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

Returns

Promise<number>

Implementation of

GrantUsageStore.getUsage

tryConsume()

tryConsume(): Promise<boolean>>

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

Returns

Promise<boolean>

Implementation of

GrantUsageStore.tryConsume

Interfaces

TestContextOptions

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

Properties

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:326
<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:327
<a id="property-enabledtoolnamespaces"></a> enabledToolNamespaces?	readonly	readonly string[]	testkit/src/index.ts:330
<a id="property-namespaceid"></a> namespaceId?	readonly	string	testkit/src/index.ts:329
<a id="property-now"></a> now?	readonly	string	testkit/src/index.ts:333
<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:328
<a id="property-purpose"></a> purpose?	readonly	string	testkit/src/index.ts:331
<a id="property-traceid"></a> traceId?	readonly	string	testkit/src/index.ts:332

---

TestGrantOptions

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

Properties

Property	Modifier	Type	Defined in
<a id="property-capabilities"></a> capabilities	readonly	readonly object[]	testkit/src/index.ts:355
<a id="property-delegationdepth"></a> delegationDepth?	readonly	number	testkit/src/index.ts:362
<a id="property-expiresat"></a> expiresAt?	readonly	string	testkit/src/index.ts:359
<a id="property-id"></a> id?	readonly	string	testkit/src/index.ts:351
<a id="property-issuedat"></a> issuedAt?	readonly	string	testkit/src/index.ts:357
<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:354
<a id="property-maxuses"></a> maxUses?	readonly	number	testkit/src/index.ts:361
<a id="property-namespaceid-1"></a> namespaceId?	readonly	string	testkit/src/index.ts:352
<a id="property-notbefore"></a> notBefore?	readonly	string	testkit/src/index.ts:358
<a id="property-parentgrantid"></a> parentGrantId?	readonly	string	testkit/src/index.ts:363
<a id="property-purposes"></a> purposes?	readonly	readonly string[]	testkit/src/index.ts:356
<a id="property-revokedat"></a> revokedAt?	readonly	string	testkit/src/index.ts:360
<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:353

---

TestKernel

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

Properties

Property	Modifier	Type	Description	Defined in
<a id="property-audit"></a> audit	readonly	InMemoryAuditSink	-	testkit/src/index.ts:288
<a id="property-grants"></a> grants	readonly	InMemoryGrantSource	The trusted store the kernel loads authority from; mutate it to grant or revoke.	testkit/src/index.ts:291
<a id="property-kernel"></a> kernel	readonly	SharedOSKernel	-	testkit/src/index.ts:287
<a id="property-messages"></a> messages	readonly	InMemoryMessageTransport	-	testkit/src/index.ts:289

---

TestKernelOptions

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

Properties

Property	Modifier	Type	Description	Defined in
<a id="property-delegationresolver"></a> delegationResolver?	readonly	DelegationChainResolver	Installs ancestor validation so delegated grants can be exercised.	testkit/src/index.ts:300
<a id="property-grants-1"></a> grants?	readonly	readonly object[]	Seed authority for the kernel's trusted grant source.	testkit/src/index.ts:296
<a id="property-grantsource"></a> grantSource?	readonly	GrantSource	Replaces the trusted grant source, for example to exercise an outage.	testkit/src/index.ts:298

Type Aliases

ResourceHandler

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

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

Parameters

Parameter	Type
operation	ResourceOperation

Returns

Promise<ResourceResult>

Functions

createTestContext()

createTestContext(options?): object

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

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[]

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

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

parentGrantId?

optional parentGrantId?: 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(options?): TestKernel

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

Parameters

Parameter	Type
options	TestKernelOptions

Returns

TestKernel