@tessar/core 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,168 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @tessar/core
+
+Tessar's TypeScript API for Agent, Controller, Session, Thread, messages,
+tools, hooks, state and checkpoints. Requires Node 24.14 or newer.
+
+```sh
+npm install @tessar/core @tessar/openai zod
+```
+
+- `Agent` owns its model, instructions, tools, limits and the agent loop.
+- `Controller({ id, agent, plugins })` owns plugin setup, resources and sessions.
+- An executable model lets Agent run directly, without public init/dispose.
+- When opting into Controller, initialize it before its sessions or plugin-backed
+  executions and dispose it when finished.
+- `agent.stream()` creates an independent task; `agent.generate()` collects the
+  same execution. A Session manages a continuing conversation with
+  `session.subscribe()` and queued `session.followUp()` inputs.
+- Core manages state and checkpoints, using memory storage by default.
+
+```ts
+import { Agent, Controller, HumanMessage, ToolMessage } from "@tessar/core";
+import { createTool } from "@tessar/core/tool";
+import { OpenAIProvider } from "@tessar/openai";
+import { z } from "zod";
+
+const addTool = createTool({
+  name: "add",
+  description: "Add two numbers",
+  schema: z.object({ a: z.number(), b: z.number() }),
+  execute: ({ a, b }) => ({ sum: a + b }),
+});
+
+const agent = new Agent({
+  id: "assistant",
+  model: new OpenAIProvider({
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: process.env.OPENAI_MODEL!,
+  }),
+  tools: { addTool },
+});
+
+const result = await agent.generate("What is 1 + 2?");
+console.log(result.output);
+```
+
+Tools can also be registered by plugins using `tessar.tools.register(addTool)`.
+Both paths share hooks and execution. Tool names must be unique.
+`tools: { concurrency: 4, addTool }` optionally limits active calls, including
+plugin tools; omit concurrency to execute the model's tool calls without a
+scheduling limit. Tools are authorized before dispatch; results enter the
+conversation in call order after the executions complete. Execution budgets
+such as `limits.maxToolCalls` still apply.
+
+`Agent.model` is required. `stream(message, options?)` and
+`generate(message, options?)` accept a string, a message, or message history.
+Each direct call has independent context and automatic per-execution cleanup.
+Use a Session when the host needs a continuing conversation.
+
+```ts
+const stream = agent.stream("Explain briefly", {
+  model: "another-model-on-the-same-connection",
+  modelOptions: { reasoning: { effort: "low" } },
+});
+for await (const event of stream) console.log(event);
+```
+
+A string model override keeps the default connection. An executable model
+instance selects its own connection and request defaults. `modelOptions`
+replaces top-level values, including whole nested objects, for that call only.
+Omitted provider settings are left to the provider SDK. Legacy object-input
+overloads/model references remain for existing Controller integrations.
+
+Zod validates arguments and infers executor input; Tessar generates the model's
+JSON Schema. Return text or JSON directly: Tessar wraps it in a `ToolMessage`
+and binds the toolCallId. Undefined and non-JSON returns fail explicitly.
+To supply content parts or metadata, return a message yourself:
+
+```ts
+new ToolMessage("Already calculated", { metadata: { source: "cache" } });
+```
+
+All messages have an ID, role, content and optional metadata. Constructors infer
+the role and generate an ID unless supplied. Metadata is persisted for hosts and
+plugins and is not automatically sent to a model. Standalone ToolMessages may
+omit toolCallId; encoding history requires it, and the tool runtime binds it
+automatically. OpenAI Responses serializes JSON tool data as JSON text.
+
+Retry, conditional availability and permissions belong in tool implementations
+or plugins. Use `tools.select` for advertised tools and `tool.before` to enforce
+execution policy. Skills and subagents are host/plugin orchestration, expressed
+to providers through instructions, messages and tools.
+
+Build instructions from sections when plugins need to append their own content:
+
+```ts
+import { buildInstruction } from "@tessar/core";
+
+const instructions = buildInstruction([
+  { id: "base", content: "You are an assistant.", order: 0 },
+  { id: "skills", content: "<skills>...</skills>", order: 100 },
+  { id: "current-context", content: "Current task details", order: 1000 },
+]);
+const agent = new Agent({ id: "assistant", model, instructions });
+```
+
+Sections sort by ascending `order`, with omitted order comparing as zero. Equal
+orders sort by ordinal ID, independent of plugin registration order. Use distinct
+orders when sequence matters. IDs must be unique and orders finite numbers.
+Building copies/freezes the data; it does not mutate caller arrays or inject a
+default order. String instructions remain supported. Final requests are normalized
+after `context.prepare` and `model.request`, including sections added by plugins.
+Ordering controls content placement; provider adapters own serialization and cache
+behavior. Core adds no cache markers or history breakpoint API.
+
+Built-in and custom plugins use classes instantiated with `new`, implementing
+the same `Plugin` instance contract. Provider adapters are separate packages,
+such as `@tessar/openai`; persistence backends such as `@tessar/sqlite` attach
+through Controller plugins.
+
+All hooks share `tessar.hook` and one typed EventMap. Import event groups directly:
+
+```ts
+import { model, thread, session } from "@tessar/core";
+
+tessar.hook(model.usage, event => console.log(event.payload.usage));
+tessar.hook(thread.beforeDelete, () => ({ decision: "deny", reason: "Keep history" }));
+tessar.hook(session.model.beforeChange, event => console.log(event.payload.model));
+```
+
+Keys start lowercase and use camelCase for hyphens in the string identifier:
+`thread.beforeDelete === "thread.before-delete"`. There is no `events` prefix.
+The old `AgentEvents` and `SessionEvents` exports are replaced by these groups.
+Session selection policies are asynchronous: use `await session.setModel(model)`
+before queuing input that should use the new model. See
+[plugin authoring](../../docs/plugin-authoring.md) for decisions and capabilities.
+
+This is an early 0.x release. See the
+[repository](https://github.com/hphucdev-04/tessar) for complete TypeScript
+examples and the current API contracts. The bundled model catalog includes its
+upstream license at `src/models/catalog.LICENSE`.
+
+## Persistent Sessions
+
+`await controller.createSession({ scope, metadata })` commits a Session record
+before returning the handle. `session.id` is generated by Tessar. Use
+`await controller.getSession(id, { scope })` to restore it and
+`await controller.listSessions({ scope, limit, cursor })` to browse this Agent's
+Sessions. A restored handle does not automatically resume unfinished work.
+
+Selections use compare-and-set: stale handles fail `CommitConflict`; reload the
+Session before retrying. Thread creation may succeed before selection fails,
+so the unselected thread remains available in the scoped thread list. Closing
+a Session keeps its record. Soft-deleting a thread clears stored selections in
+the same transaction. Subscribers and unadmitted followUp queues stay in memory.
+
+There is no Agent table. The application constructs its Agent and supplies the
+same `agentId` and compatible providers/plugins on restart. Controller's ID is
+not a persistence key. Session creation notifications are available to Controller
+plugins; subscribe on the returned handle for subsequent events. Restoration
+does not emit another `session.created` notification.
+
+`controller.deleteThread` is a soft delete. `controller.purgeThread` permanently
+removes only a deleted, inactive, unowned thread with no retained fork referencing
+it. Both invoke thread deletion policy; purge supplies `permanent: true`.
+
+Storage adapter authors must implement the new `sessions` CAS port, backend page
+and history queries, `threads.get(..., { includeDeleted })` and `threads.purge`.
+These are breaking storage-port changes; run storage conformance and query tests.

package/dist/agent.d.ts

@@ -0,0 +1,78 @@
+import type { Controller } from "./controller.js";
+import type { Model } from "./models/profile.js";
+import type { ModelAdapter, ModelOptions, ModelRef } from "./models/contract.js";
+import type { Scope, InterruptRecord, StreamLimits } from "./state/schema.js";
+import type { StreamRecord } from "./trace/records.js";
+import type { StorageBackend } from "./state/storage-ports.js";
+import type { PluginHost } from "./plugins/host.js";
+import { type Stream, type DeliveryTarget } from "./engine/delivery.js";
+export type { Stream, DeliveryTarget } from "./engine/delivery.js";
+import { type ErrorInfo } from "./errors.js";
+import { type Clock, type IdGenerator, type JsonObject } from "./json.js";
+import { type Instruction } from "./instructions/instruction.js";
+import type { MessageData } from "./messages/message.js";
+import { Tool } from "./tools/tool.js";
+import type { ExecutionRequest } from "./engine/frame.js";
+export type { ExecutionFrame, ExecutionRequest, ExecutionOrigin, } from "./engine/frame.js";
+import type { ExecutionRuntime } from "./engine/runtime.js";
+export type ModelSelection = ModelAdapter | Model | ModelRef;
+export type AgentInput = string | MessageData | readonly MessageData[];
+export interface AgentOptions<M extends ModelSelection = ModelSelection> {
+    id: string;
+    model: M;
+    instructions?: string | Instruction;
+    limits?: Partial<StreamLimits>;
+    tools?: AgentTools;
+}
+export interface AgentTools {
+    concurrency?: number;
+    readonly [alias: string]: Tool | number | undefined;
+}
+export interface AgentExecutionOptions<M = ModelAdapter> {
+    model?: M | Model | ModelRef | string;
+    modelOptions?: ModelOptions<M>;
+    scope?: Scope;
+    context?: JsonObject;
+    signal?: AbortSignal;
+    limits?: Partial<StreamLimits>;
+}
+export interface GenerateOutcome {
+    threadId: string;
+    streamId: string;
+    status: StreamRecord["status"];
+    output: readonly MessageData[];
+    usage: import("./trace/usage.js").UsageSummary;
+    interrupt: InterruptRecord | null;
+    error: ErrorInfo | null;
+}
+export declare function inputMessages(input: MessageData | readonly MessageData[]): readonly MessageData[];
+export declare class Agent<M extends ModelSelection = ModelSelection> {
+    readonly id: string;
+    readonly tools: readonly Tool[];
+    /** @internal */ readonly toolConcurrency: number;
+    readonly model: M;
+    private controller?;
+    /** @internal */ attachController(controller: Controller): void;
+    private runtime;
+    get backend(): StorageBackend;
+    get registry(): PluginHost;
+    readonly ids: IdGenerator;
+    readonly clock: Clock;
+    readonly limits: StreamLimits;
+    readonly instructions: Instruction;
+    private readonly jobs;
+    private readonly outcomes;
+    private readonly active;
+    private readonly pendingModels;
+    private closed;
+    private readonly releaseId;
+    private readonly resumeAdmissions;
+    constructor(options: AgentOptions<M>);
+    stream<T extends ModelAdapter = Extract<M, ModelAdapter>>(input: AgentInput, options?: AgentExecutionOptions<T>): Stream;
+    generate<T extends ModelAdapter = Extract<M, ModelAdapter>>(input: AgentInput, options?: AgentExecutionOptions<T>): Promise<GenerateOutcome>;
+    /** @internal Shared admission for Thread, Session and testing. */
+    admit(request: ExecutionRequest, target?: DeliveryTarget, prepare?: () => Promise<void>, runtime?: ExecutionRuntime, cleanup?: () => Promise<void>): Stream;
+    private executionContext;
+    cancel(threadId: string, streamId: string, reason?: string, target?: DeliveryTarget, context?: Pick<ExecutionRequest, "session" | "thread">): Promise<void>;
+    shutdown(): Promise<void>;
+}

package/dist/agent.js

@@ -0,0 +1,189 @@
+import { stream as streamHooks } from "./events/type.js";
+import { createDelivery, } from "./engine/delivery.js";
+import { errorInfo, errorFromInfo, fail, requireId, } from "./errors.js";
+import { immutable, randomIds, systemClock, } from "./json.js";
+import { normalizeInstruction, } from "./instructions/instruction.js";
+import { MessageCodec } from "./messages/codec.js";
+import { Tool } from "./tools/tool.js";
+import { execute, cancel } from "./engine/execution.js";
+import { hook } from "./engine/hooks.js";
+import { put, rows, commit, updateUsage, prepareMessage, appendMessage, finish, } from "./engine/checkpoint.js";
+import { services } from "./engine/services.js";
+import { callAgent, modelRef, readOutcome } from "./engine/call.js";
+import { isModelAdapter } from "./models/stream.js";
+import { reserveId } from "./identity.js";
+export function inputMessages(input) {
+    const values = Array.isArray(input) ? input : [input];
+    return values.map((value) => MessageCodec.encode(MessageCodec.decode(MessageCodec.encode(value))));
+}
+function validateLimits(limits) {
+    for (const value of Object.values(limits))
+        if (!Number.isInteger(value) || value < 1)
+            fail("InvalidConfiguration", "Limits must be positive integers");
+}
+export class Agent {
+    id;
+    tools;
+    /** @internal */ toolConcurrency;
+    model;
+    controller;
+    /** @internal */ attachController(controller) {
+        if (this.controller)
+            fail("AgentAlreadyBound", "Agent already belongs to a Controller");
+        this.controller = controller;
+    }
+    runtime() {
+        if (!this.controller)
+            fail("ControllerNotReady", "Initialize a Controller for this Agent");
+        return this.controller;
+    }
+    get backend() {
+        return this.runtime().backend;
+    }
+    get registry() {
+        return this.runtime().hooks;
+    }
+    ids;
+    clock;
+    limits;
+    instructions;
+    jobs = new Set();
+    outcomes = new WeakMap();
+    active = new Map();
+    pendingModels = new Map();
+    closed = false;
+    releaseId;
+    resumeAdmissions = new Map();
+    constructor(options) {
+        this.id = requireId(options.id, "agent id");
+        if (!options.model)
+            fail("MissingModel", "Agent requires a default model");
+        const { concurrency, ...tools } = options.tools ?? {};
+        if (concurrency !== undefined &&
+            (!Number.isInteger(concurrency) || concurrency < 1))
+            fail("InvalidConfiguration", "Tool concurrency must be a positive integer");
+        const values = Object.values(tools);
+        if (values.some((tool) => !(tool instanceof Tool)))
+            fail("InvalidConfiguration", "Agent tools must be Tool instances");
+        this.tools = Object.freeze(values);
+        if (new Set(this.tools.map((tool) => tool.name)).size !== this.tools.length)
+            fail("RegistrationConflict", "Tool name already registered");
+        this.toolConcurrency = concurrency ?? Infinity;
+        this.model = ("ref" in options.model ? options.model : immutable(options.model));
+        const ref = modelRef(this.model);
+        requireId(ref.providerId, "provider id");
+        requireId(ref.modelId, "model id");
+        this.ids = randomIds;
+        this.clock = systemClock;
+        this.instructions = normalizeInstruction(options.instructions);
+        this.limits = immutable({
+            maxTurns: 32,
+            maxModelAttempts: 64,
+            maxToolCalls: 128,
+            ...options.limits,
+        });
+        validateLimits(this.limits);
+        this.releaseId = reserveId("Agent", this.id, this);
+    }
+    stream(input, options = {}) {
+        return callAgent(this, input, options, this.controller);
+    }
+    async generate(input, options = {}) {
+        const stream = this.stream(input, options);
+        for await (const event of stream)
+            if (event.is(streamHooks.error))
+                throw errorFromInfo(event.payload.error);
+        return this.outcomes.get(stream);
+    }
+    /** @internal Shared admission for Thread, Session and testing. */
+    admit(request, target = { kind: "iterator" }, prepare, runtime, cleanup) {
+        const environment = runtime ?? this.runtime();
+        if (environment === this.controller)
+            this.controller.requireReady();
+        if (this.closed)
+            fail("Disposed", "Agent closed");
+        if (request.kind === "input")
+            validateLimits({ ...this.limits, ...request.limits });
+        if (!request.adapter &&
+            isModelAdapter(this.model) &&
+            request.model?.providerId === this.model.ref.providerId &&
+            request.model.connectionId === this.model.ref.connectionId) {
+            request = {
+                ...request,
+                adapter: request.model.modelId === this.model.ref.modelId
+                    ? this.model
+                    : this.model.withModel?.(request.model.modelId),
+            };
+        }
+        const sink = createDelivery(request.threadId, this.ids, target, request.signal, environment.report);
+        const registry = environment.hooks.capture();
+        const outcome = (async () => {
+            let entered = false;
+            try {
+                await prepare?.();
+                if (this.closed)
+                    fail("Disposed", "Agent closed");
+                entered = true;
+                const failure = await execute(this.executionContext(environment), request, sink, registry);
+                if (failure !== undefined && errorInfo(failure).source === "provider")
+                    throw failure;
+                return await readOutcome(environment, sink.stream);
+            }
+            catch (error) {
+                if (!entered)
+                    await registry.release();
+                environment.report(errorInfo(error));
+                sink.emit(streamHooks.error, {
+                    error: errorInfo(error),
+                    lastKnownCheckpointId: null,
+                    persistedStatus: null,
+                }, {});
+                sink.rejected(errorInfo(error));
+                sink.close();
+                throw error;
+            }
+            finally {
+                await cleanup?.();
+            }
+        })();
+        this.outcomes.set(sink.stream, outcome);
+        const job = outcome.then(() => { }, () => { });
+        this.jobs.add(job);
+        void job.then(() => this.jobs.delete(job));
+        return sink.stream;
+    }
+    executionContext(runtime = this.runtime()) {
+        const execution = {
+            agent: this,
+            runtime,
+            active: this.active,
+            pendingModels: this.pendingModels,
+            resumeAdmissions: this.resumeAdmissions,
+            ids: this.ids,
+            clock: this.clock,
+            toolConcurrency: this.toolConcurrency,
+            hook: (frame, definition, payload, toolExecutionId) => hook(execution, frame, definition, payload, toolExecutionId),
+            put,
+            rows,
+            commit: (frame, cause) => commit(execution, frame, cause),
+            updateUsage: (frame) => updateUsage(execution, frame),
+            prepareMessage: (frame, message) => prepareMessage(execution, frame, message),
+            appendMessage: (frame, message) => appendMessage(execution, frame, message),
+            services: (frame, toolExecutionId) => services(execution, frame, toolExecutionId),
+            finish: (frame, status, reason, error) => finish(execution, frame, status, reason, error),
+        };
+        return execution;
+    }
+    async cancel(threadId, streamId, reason = "Cancelled", target = { kind: "observer", observe: () => { } }, context = {}) {
+        return cancel(this.executionContext(), threadId, streamId, reason, target, context);
+    }
+    async shutdown() {
+        this.closed = true;
+        for (const frame of this.active.values())
+            frame.sink.controller.abort("Controller disposed");
+        await Promise.allSettled([...this.jobs]);
+        this.pendingModels.clear();
+        this.releaseId();
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/controller.d.ts

@@ -0,0 +1,62 @@
+import { type ErrorInfo } from "./errors.js";
+import type { StoredModelSelection, SessionRecord } from "./state/schema.js";
+import { type EventContext } from "./events/definition.js";
+import { PluginHost } from "./plugins/host.js";
+import type { Plugin } from "./plugins/context.js";
+import type { Agent, ModelSelection } from "./agent.js";
+import type { Model } from "./models/profile.js";
+import { ModelRegistry } from "./models/registry.js";
+import type { StorageBackend } from "./state/storage-ports.js";
+import { StateQueries } from "./state/queries.js";
+import { type CreateThreadOptions } from "./state/threads.js";
+import { type ForkOptions } from "./state/fork.js";
+import type { PageOptions, StateQuery, ThreadInfo } from "./state/schema.js";
+import { Thread } from "./thread.js";
+import { Session, type SessionOptions } from "./session.js";
+export declare class Controller {
+    readonly id: string;
+    readonly agent: Agent;
+    readonly models: ModelRegistry;
+    readonly diagnostics: ErrorInfo[];
+    readonly report: (error: ErrorInfo, context?: EventContext) => void;
+    /** @internal */ readonly hooks: PluginHost;
+    /** @internal */ backend: StorageBackend;
+    /** @internal */ queries: StateQueries;
+    private phase;
+    private initialization?;
+    private readonly initialPlugins;
+    private disposal?;
+    private readonly releaseId;
+    private defaultBackend;
+    private readonly providers;
+    readonly plugins: {
+        attach: (plugin: Plugin) => Promise<void>;
+        detach: (id: string) => Promise<void>;
+    };
+    constructor(options: {
+        id: string;
+        agent: Agent;
+        plugins?: readonly Plugin[];
+    });
+    initialize(): Promise<void>;
+    /** @internal */ requireReady(): void;
+    private syncProviders;
+    /** @internal */ resolveModel(value: ModelSelection | undefined): Model;
+    /** @internal */ prepareThread(options?: CreateThreadOptions, reservedId?: string): Promise<ThreadInfo>;
+    createThread(options?: CreateThreadOptions): Promise<Thread>;
+    /** @internal */ sessionModel(value: ModelSelection): {
+        model: Model;
+        stored: StoredModelSelection;
+    };
+    createSession(options?: SessionOptions): Promise<Session>;
+    getSession(id: string, query?: StateQuery): Promise<Session | null>;
+    listSessions(query?: StateQuery & PageOptions): Promise<import("./state/schema.js").Page<SessionRecord>>;
+    getThread(id: string, query?: StateQuery): Promise<Thread | null>;
+    listThreads(query?: StateQuery & PageOptions): Promise<import("./state/schema.js").Page<ThreadInfo>>;
+    deleteThread(id: string, query?: StateQuery): Promise<void>;
+    purgeThread(id: string, query?: StateQuery): Promise<void>;
+    renameThread(id: string, title: string, query?: StateQuery): Promise<void>;
+    forkThread(id: string, options?: ForkOptions & StateQuery): Promise<Thread>;
+    private threadContext;
+    dispose(): Promise<void>;
+}