@sms/contracts

Parameter	Type
`make`	(`bridge`) => `SessionBackend`
`opts`	`SessionBridgeOptions`

Parameter	Type
`err`	`unknown`

Parameter	Type
`error?`	`string`

Interfaces

Database

Defined in: packages/core/contracts/src/index.ts:33

A relational database as the collections plugin and the SQL store see it. Placeholders are always ? — a driver rewrites them for its engine. Inserts return their id with RETURNING id (SQLite ≥ 3.35, Postgres, DO SQLite all support it).

Properties

dialect

readonly dialect: Dialect;

Defined in: packages/core/contracts/src/index.ts:34

Methods

close()

close(): Promise<void>;

Defined in: packages/core/contracts/src/index.ts:41

Returns

Promise<void>

columns()

columns(table): Promise<string[]>;

Defined in: packages/core/contracts/src/index.ts:40

Column names of a table; [] if it does not exist.

Parameters

Parameter	Type
`table`	`string`

Returns

Promise<string[]>

exec()

exec(sql): Promise<void>;

Defined in: packages/core/contracts/src/index.ts:36

Run one or more statements without results (DDL).

Parameters

Parameter	Type
`sql`	`string`

Returns

Promise<void>

query()

query<T>(sql, params?): Promise<T[]>;

Defined in: packages/core/contracts/src/index.ts:38

Run one statement with ? placeholders and return its rows.

Type Parameters

Type Parameter	Default type
`T`	`Record`<`string`, `unknown`>

Parameters

Parameter	Type
`sql`	`string`
`params?`	`unknown`[]

Returns

Promise<T[]>

Deferred

Defined in: packages/core/contracts/src/model-session.ts:27

Type Parameters

Type Parameter
`T`

Properties

promise

promise: Promise<T>;

Defined in: packages/core/contracts/src/model-session.ts:28

reject

reject: (e) => void;

Defined in: packages/core/contracts/src/model-session.ts:30

Parameters

Parameter	Type
`e`	`unknown`

Returns

void

resolve

resolve: (v) => void;

Defined in: packages/core/contracts/src/model-session.ts:29

Parameters

Parameter	Type
`v`	`T`

Returns

void

Host

Defined in: packages/core/contracts/src/index.ts:64

An HTTP host: takes a fetch-style handler and puts it on the wire.

Methods

listen()

listen(handler): Promise<HostServer>;

Defined in: packages/core/contracts/src/index.ts:65

Parameters

Parameter	Type
`handler`	`RequestHandler`

Returns

Promise<HostServer>

HostServer

Defined in: packages/core/contracts/src/index.ts:57

Properties

url?

optional url?: string;

Defined in: packages/core/contracts/src/index.ts:59

Base URL when the host listens on a socket (absent for serverless hosts).

Methods

close()

close(): Promise<void>;

Defined in: packages/core/contracts/src/index.ts:60

Returns

Promise<void>

ListObjectsOptions

Defined in: packages/core/contracts/src/objects.ts:28

Properties

cursor?

optional cursor?: string;

Defined in: packages/core/contracts/src/objects.ts:35

Opaque token from a previous page’s cursor.

delimiter?

optional delimiter?: string;

Defined in: packages/core/contracts/src/objects.ts:31

'/' groups keys under the next delimiter into prefixes (folder-style listing).

limit?

optional limit?: number;

Defined in: packages/core/contracts/src/objects.ts:33

Page size; the backend’s own maximum applies.

prefix?

optional prefix?: string;

Defined in: packages/core/contracts/src/objects.ts:29

ModelMessage

Defined in: packages/core/contracts/src/model.ts:14

Properties

content

content: ModelContent[];

Defined in: packages/core/contracts/src/model.ts:16

role

role: "user" | "assistant";

Defined in: packages/core/contracts/src/model.ts:15

ModelRequest

Defined in: packages/core/contracts/src/model.ts:26

Properties

messages

messages: ModelMessage[];

Defined in: packages/core/contracts/src/model.ts:28

system

system: string;

Defined in: packages/core/contracts/src/model.ts:27

tools

tools: ModelTool[];

Defined in: packages/core/contracts/src/model.ts:29

ModelResponse

Defined in: packages/core/contracts/src/model.ts:32

Properties

content

content: ModelContent[];

Defined in: packages/core/contracts/src/model.ts:33

stopReason

stopReason: string;

Defined in: packages/core/contracts/src/model.ts:35

'end_turn', 'tool_use', or a provider-specific reason. The loop only looks at content.

ModelService

Defined in: packages/core/contracts/src/model.ts:49

Properties

name

name: string;

Defined in: packages/core/contracts/src/model.ts:50

Methods

complete()

complete(req): Promise<ModelResponse>;

Defined in: packages/core/contracts/src/model.ts:51

Parameters

Parameter	Type
`req`	`ModelRequest`

Returns

Promise<ModelResponse>

stream()?

optional stream(req): AsyncIterable<ModelEvent>;

Defined in: packages/core/contracts/src/model.ts:53

Optional: the same turn as complete(), incrementally. Consumers use streamOf() to not care.

Parameters

Parameter	Type
`req`	`ModelRequest`

Returns

AsyncIterable<ModelEvent>

ModelTool

Defined in: packages/core/contracts/src/model.ts:19

Properties

description

description: string;

Defined in: packages/core/contracts/src/model.ts:21

input_schema

input_schema: Record<string, unknown>;

Defined in: packages/core/contracts/src/model.ts:23

JSON schema of the tool input (an object schema; type: 'object' is implied).

name

name: string;

Defined in: packages/core/contracts/src/model.ts:20

ObjectContent

Defined in: packages/core/contracts/src/objects.ts:47

A get() result: the metadata plus the bytes, as a stream or collected.

Extends

ObjectMeta

Properties

body

body: ReadableStream<Uint8Array<ArrayBufferLike>>;

Defined in: packages/core/contracts/src/objects.ts:48

contentType?

optional contentType?: string;

Defined in: packages/core/contracts/src/objects.ts:16

Inherited from

ObjectMeta.contentType

etag?

optional etag?: string;

Defined in: packages/core/contracts/src/objects.ts:18

Backend entity tag (unquoted); absent on backends that do not expose one.

Inherited from

ObjectMeta.etag

key

key: string;

Defined in: packages/core/contracts/src/objects.ts:11

Inherited from

ObjectMeta.key

lastModified

lastModified: number;

Defined in: packages/core/contracts/src/objects.ts:15

Unix ms.

Inherited from

ObjectMeta.lastModified

metadata

metadata: Record<string, string>;

Defined in: packages/core/contracts/src/objects.ts:20

User metadata (x-amz-meta-* / R2 customMetadata). Keys are lower-case.

Inherited from

ObjectMeta.metadata

size

size: number;

Defined in: packages/core/contracts/src/objects.ts:13

Bytes.

Inherited from

ObjectMeta.size

Methods

bytes()

bytes(): Promise<Uint8Array<ArrayBufferLike>>;

Defined in: packages/core/contracts/src/objects.ts:49

Returns

Promise<Uint8Array<ArrayBufferLike>>

text()

text(): Promise<string>;

Defined in: packages/core/contracts/src/objects.ts:50

Returns

Promise<string>

ObjectList

Defined in: packages/core/contracts/src/objects.ts:38

Properties

cursor?

optional cursor?: string;

Defined in: packages/core/contracts/src/objects.ts:43

Present when there is another page.

objects

objects: ObjectMeta[];

Defined in: packages/core/contracts/src/objects.ts:39

prefixes

prefixes: string[];

Defined in: packages/core/contracts/src/objects.ts:41

Only with delimiter.

ObjectMeta

Defined in: packages/core/contracts/src/objects.ts:10

Extended by

ObjectContent

Properties

contentType?

optional contentType?: string;

Defined in: packages/core/contracts/src/objects.ts:16

etag?

optional etag?: string;

Defined in: packages/core/contracts/src/objects.ts:18

Backend entity tag (unquoted); absent on backends that do not expose one.

key

key: string;

Defined in: packages/core/contracts/src/objects.ts:11

lastModified

lastModified: number;

Defined in: packages/core/contracts/src/objects.ts:15

Unix ms.

metadata

metadata: Record<string, string>;

Defined in: packages/core/contracts/src/objects.ts:20

User metadata (x-amz-meta-* / R2 customMetadata). Keys are lower-case.

size

size: number;

Defined in: packages/core/contracts/src/objects.ts:13

Bytes.

ObjectStore

Defined in: packages/core/contracts/src/objects.ts:53

Methods

delete()

delete(key): Promise<void>;

Defined in: packages/core/contracts/src/objects.ts:59

Idempotent: deleting a missing key is not an error.

Parameters

Parameter	Type
`key`	`string`

Returns

Promise<void>

get()

get(key): Promise<ObjectContent | undefined>;

Defined in: packages/core/contracts/src/objects.ts:56

undefined when the key does not exist.

Parameters

Parameter	Type
`key`	`string`

Returns

Promise<ObjectContent | undefined>

head()

head(key): Promise<ObjectMeta | undefined>;

Defined in: packages/core/contracts/src/objects.ts:57

Parameters

Parameter	Type
`key`	`string`

Returns

Promise<ObjectMeta | undefined>

list()

list(opts?): Promise<ObjectList>;

Defined in: packages/core/contracts/src/objects.ts:60

Parameters

Parameter	Type
`opts?`	`ListObjectsOptions`

Returns

Promise<ObjectList>

put()

put(
   key, 
   body, 
   opts?
): Promise<ObjectMeta>;

Defined in: packages/core/contracts/src/objects.ts:54

Parameters

Parameter	Type
`key`	`string`
`body`	`ObjectBody`
`opts?`	`PutObjectOptions`

Returns

Promise<ObjectMeta>

PutObjectOptions

Defined in: packages/core/contracts/src/objects.ts:23

Properties

contentType?

optional contentType?: string;

Defined in: packages/core/contracts/src/objects.ts:24

metadata?

optional metadata?: Record<string, string>;

Defined in: packages/core/contracts/src/objects.ts:25

SessionBackend

Defined in: packages/core/contracts/src/model-session.ts:69

What a driver supplies: the SDK-specific half of a session.

Methods

close()

close(): void;

Defined in: packages/core/contracts/src/model-session.ts:80

Returns

void

send()

send(text): void | Promise<void>;

Defined in: packages/core/contracts/src/model-session.ts:79

Deliver the user’s text for a new turn.

Parameters

Parameter	Type
`text`	`string`

Returns

void | Promise<void>

setTools()

setTools(tools): void | Promise<void>;

Defined in: packages/core/contracts/src/model-session.ts:77

The tool set changed (mid-turn or between turns).

Parameters

Parameter	Type
`tools`	`ModelTool`[]

Returns

void | Promise<void>

start()

start(
   system, 
   tools, 
   prior
): void | Promise<void>;

Defined in: packages/core/contracts/src/model-session.ts:75

(Re)start the SDK session with this system prompt and tool set. Called before the first user turn and whenever the system prompt changes. prior is the loop’s history before the current message: replay it (see transcript) when the backend cannot resume an earlier session.

Parameters

Parameter	Type
`system`	`string`
`tools`	`ModelTool`[]
`prior`	`ModelMessage`[]

Returns

void | Promise<void>

SessionBridgeOptions

Defined in: packages/core/contracts/src/model-session.ts:83

Properties

debug?

optional debug?: (...args) => void;

Defined in: packages/core/contracts/src/model-session.ts:86

Parameters

Parameter	Type
…`args`	`unknown`[]

Returns

void

flushDelayMs?

optional flushDelayMs?: number;

Defined in: packages/core/contracts/src/model-session.ts:88

Delay before handing a tool_use batch to the loop, so parallel calls arrive together.

tag?

optional tag?: string;

Defined in: packages/core/contracts/src/model-session.ts:85

Prefix for debug lines, e.g. the driver name.

Store

Defined in: packages/core/contracts/src/index.ts:45

Everything a kernel needs to persist: the event log, bundle blobs, and a database for plugins (key database).

Extended by

SqliteStore

Properties

blobs

blobs: BlobStore;

Defined in: packages/core/contracts/src/index.ts:48

db

db: Database;

Defined in: packages/core/contracts/src/index.ts:46

log

log: EventLog;

Defined in: packages/core/contracts/src/index.ts:47

Methods

close()

close(): Promise<void>;

Defined in: packages/core/contracts/src/index.ts:49

Returns

Promise<void>

SubdomainOptions

Defined in: packages/core/contracts/src/index.ts:77

Properties

fallback?

optional fallback?: string;

Defined in: packages/core/contracts/src/index.ts:79

Tenant when the host has no tenant label (bare root domain, localhost, an IP).

reserved?

optional reserved?: Iterable<string, any, any>;

Defined in: packages/core/contracts/src/index.ts:83

Labels that are never tenants (www, api…): resolve to undefined.

root?

optional root?: string;

Defined in: packages/core/contracts/src/index.ts:81

The domain tenants live under (example.com). Without it the first label of any host is the tenant.

ToolCallResult

Defined in: packages/core/contracts/src/model-session.ts:22

Properties

content

content: string;

Defined in: packages/core/contracts/src/model-session.ts:23

isError?

optional isError?: boolean;

Defined in: packages/core/contracts/src/model-session.ts:24

Type Aliases

Dialect

type Dialect = "sqlite" | "postgres";

Defined in: packages/core/contracts/src/index.ts:14

ModelContent

type ModelContent = 
  | {
  text: string;
  type: "text";
}
  | {
  id: string;
  input: unknown;
  name: string;
  type: "tool_use";
}
  | {
  content: string;
  is_error?: boolean;
  tool_use_id: string;
  type: "tool_result";
};

Defined in: packages/core/contracts/src/model.ts:9

ModelEvent

type ModelEvent = 
  | {
  text: string;
  type: "text_delta";
}
  | {
  text: string;
  type: "thinking_delta";
}
  | {
  block: Extract<ModelContent, {
     type: "tool_use";
  }>;
  type: "tool_use";
}
  | {
  response: ModelResponse;
  type: "done";
};

Defined in: packages/core/contracts/src/model.ts:43

What a streaming driver emits while producing one turn. Deltas arrive as the provider sends them; tool_use is emitted once a call’s arguments are complete; done always ends the stream and carries the same ModelResponse that complete() would have returned for the request.

ObjectBody

type ObjectBody = string | Uint8Array | ArrayBuffer | ReadableStream<Uint8Array>;

Defined in: packages/core/contracts/src/objects.ts:8

Bytes going in: a string is UTF-8 encoded; a stream is passed through where the backend supports it.

RequestHandler

type RequestHandler = (request) => Promise<Response>;

Defined in: packages/core/contracts/src/index.ts:55

Parameters

Parameter	Type
`request`	`Request`

Returns

Promise<Response>

TenantResolver

type TenantResolver = (request) => string | undefined | Promise<string | undefined>;

Defined in: packages/core/contracts/src/index.ts:69

Maps a request to a tenant id. undefined = no tenant (reject or use a default, host’s choice).

Parameters

Parameter	Type
`request`	`Request`

Returns

string | undefined | Promise<string | undefined>

Variables

DATABASE_KEY

const DATABASE_KEY: "database" = 'database';

Defined in: packages/core/contracts/src/index.ts:53

The key under which the composition root provides the Database (system ↔ system).

MODEL_KEY

const MODEL_KEY: "model" = 'model';

Defined in: packages/core/contracts/src/model.ts:73

The key under which the model driver is provided (system → agent-loop).

OBJECTS_KEY

const OBJECTS_KEY: "objects" = 'objects';

Defined in: packages/core/contracts/src/objects.ts:64

The key under which the composition root provides the ObjectStore (system ↔ system, like database).

Functions

assertObjectKey()

function assertObjectKey(key): void;

Defined in: packages/core/contracts/src/objects.ts:69

Object keys are paths without a leading /, //, ./.. segments or control characters.

Parameters

Parameter	Type
`key`	`string`

Returns

void

assertTenantId()

function assertTenantId(id): void;

Defined in: packages/core/contracts/src/index.ts:114

Tenant ids become file names / schema names: keep them boring.

Parameters

Parameter	Type
`id`	`string`

Returns

void

bodyToBytes()

function bodyToBytes(body): Promise<Uint8Array<ArrayBufferLike>>;

Defined in: packages/core/contracts/src/objects.ts:75

Collect any ObjectBody into bytes (drivers that cannot stream use this).

Parameters

Parameter	Type
`body`	`ObjectBody`

Returns

Promise<Uint8Array<ArrayBufferLike>>

conversationKey()

function conversationKey(req): string;

Defined in: packages/core/contracts/src/model-session.ts:300

Sessions are identified by the first user message of the loop’s history.

Parameters

Parameter	Type
`req`	`ModelRequest`

Returns

string

createMemoryObjectStore()

function createMemoryObjectStore(): ObjectStore;

Defined in: packages/core/contracts/src/objects.ts:151

In-memory reference implementation: tests, and the contract suite’s oracle.

Returns

ObjectStore

createModelPlugin()

function createModelPlugin(id, model): SystemPlugin;

Defined in: packages/core/contracts/src/model.ts:104

Wrap any ModelService as a system plugin providing model.

Parameters

Parameter	Type
`id`	`string`
`model`	`ModelService`

Returns

SystemPlugin

createReasoningCache()

function createReasoningCache<T>(max?): Pick<Map<string, T>, "get"> & {
  set: void;
};

Defined in: packages/core/contracts/src/model.ts:90

Bounded FIFO map for provider-side reasoning items that must be replayed with the next tool call.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type	Default value
`max`	`number`	`256`

Returns

Pick<Map<string, T>, "get"> & { set: void; }

createScriptedModel()

function createScriptedModel(turns): ModelService & {
  calls: ModelRequest[];
  stream: AsyncIterable<ModelEvent>;
};

Defined in: packages/core/contracts/src/model.ts:115

A scripted model for tests and offline demos: each turn pops the next canned response. stream() replays the same turn as events, text split per word so consumers see several deltas.

Parameters

Parameter	Type
`turns`	(`req`) => \| `string` \| `ModelResponse` \| `ModelContent`[][]

Returns

ModelService & { calls: ModelRequest[]; stream: AsyncIterable<ModelEvent>; }

createSessionModel()

function createSessionModel(name, session): ModelService & {
  close: void;
};

Defined in: packages/core/contracts/src/model-session.ts:305

A ModelService with one SessionBridge per conversation.

Parameters

Parameter	Type
`name`	`string`
`session`	() => `SessionBridge`

Returns

ModelService & { close: void; }

deferred()

function deferred<T>(): Deferred<T>;

Defined in: packages/core/contracts/src/model-session.ts:32

Type Parameters

Type Parameter
`T`

Returns

Deferred<T>

eventsOf()

function eventsOf(response): Iterable<ModelEvent>;

Defined in: packages/core/contracts/src/model.ts:64

Replay a finished response as events (text as one delta, each tool call, then done).

Parameters

Parameter	Type
`response`	`ModelResponse`

Returns

Iterable<ModelEvent>

firstToolUseId()

function firstToolUseId(content): string | undefined;

Defined in: packages/core/contracts/src/model.ts:85

Id of the first tool_use block — the handle drivers key per-turn provider state (reasoning) on.

Parameters

Parameter	Type
`content`	`ModelContent`[]

Returns

string | undefined

listKeys()

function listKeys(entries, opts?): ObjectList;

Defined in: packages/core/contracts/src/objects.ts:119

Shared S3-style listing over a set of objects; used by the memory store and the drivers’ fakes.

Parameters

Parameter	Type
`entries`	`Iterable`<`ObjectMeta`>
`opts`	`ListObjectsOptions`

Returns

ObjectList

lowerKeys()

function lowerKeys(m): Record<string, string>;

Defined in: packages/core/contracts/src/objects.ts:147

Parameters

Parameter	Type
`m`	`Record`<`string`, `string`>

Returns

Record<string, string>

objectContent()

function objectContent(source): {
  body: ReadableStream<Uint8Array<ArrayBufferLike>>;
  bytes: () => Promise<Uint8Array<ArrayBufferLike>>;
  text: () => Promise<string>;
};

Defined in: packages/core/contracts/src/objects.ts:96

The body part of an ObjectContent from a stream (or bytes).

Parameters

Parameter	Type
`source`	\| `Uint8Array`<`ArrayBufferLike`> \| `ReadableStream`<`Uint8Array`<`ArrayBufferLike`>>

Returns

{
  body: ReadableStream<Uint8Array<ArrayBufferLike>>;
  bytes: () => Promise<Uint8Array<ArrayBufferLike>>;
  text: () => Promise<string>;
}

body

body: ReadableStream<Uint8Array<ArrayBufferLike>>;

bytes

bytes: () => Promise<Uint8Array<ArrayBufferLike>> = collect;

Returns

Promise<Uint8Array<ArrayBufferLike>>

text

text: () => Promise<string>;

Returns

Promise<string>

parseToolArgs()

function parseToolArgs(raw): unknown;

Defined in: packages/core/contracts/src/model.ts:76

Parse a tool call’s JSON arguments string; unparsable text is kept as { _raw } so the tool sees it.

Parameters

Parameter	Type
`raw`	`string`

Returns

unknown

replayPrompt()

function replayPrompt(prior): string;

Defined in: packages/core/contracts/src/model-session.ts:295

transcript() framed as the opening message of an SDK session that cannot resume.

Parameters

Parameter	Type
`prior`	`ModelMessage`[]

Returns

string

sqlDialect()

function sqlDialect(dialect): {
  bigint: string;
  boolean: string;
  idColumn: string;
  real: string;
};

Defined in: packages/core/contracts/src/index.ts:17

Dialect-specific DDL fragments; pure, shared by store drivers and the collections plugin.

Parameters

Parameter	Type
`dialect`	`Dialect`

Returns

bigint

bigint: string;

boolean

boolean: string;

idColumn

idColumn: string;

auto-increment integer primary key

real

real: string;

streamOf()

function streamOf(model, req): AsyncIterable<ModelEvent>;

Defined in: packages/core/contracts/src/model.ts:57

Stream a turn from any driver: a driver without stream() yields its complete() as one text + done.

Parameters

Parameter	Type
`model`	`ModelService`
`req`	`ModelRequest`

Returns

AsyncIterable<ModelEvent>

tenantFromHeader()

function tenantFromHeader(header?, fallback?): TenantResolver;

Defined in: packages/core/contracts/src/index.ts:73

Tenant id from a header (default x-tenant), falling back to fallback.

Parameters

Parameter	Type	Default value
`header`	`string`	`'x-tenant'`
`fallback?`	`string`	`undefined`

Returns

TenantResolver

tenantFromSubdomain()

function tenantFromSubdomain(opts?): TenantResolver;

Defined in: packages/core/contracts/src/index.ts:93

Tenant id from the host-name label under root (acme.example.com → acme). localhost, IPs and the bare root resolve to fallback; acme.localhost → acme for local development without DNS. tenantFromSubdomain('dev') is shorthand for { fallback: 'dev' }.