@tessar/core 0.1.0-alpha.0 → 0.1.0

package/README.md

@@ -1,31 +1,168 @@
-# @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@next
-```
-
-- `Agent` owns its model/instructions/limits and the agent loop.
-- `Controller({ id, agent, plugins })` owns plugin setup, resources and sessions.
-- Call `controller.initialize()` before Agent or Session execution, and
-  `controller.dispose()` 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, type Plugin } from "@tessar/core";
-import { createTool, toolResult } from "@tessar/core/tool";
-```
-
-Built-in and custom plugins use classes instantiated with `new`, implementing
-the same `Plugin` instance contract. Providers and persistence backends are
-separate plugins: `@tessar/openai` and `@tessar/sqlite`.
-
-This is an alpha 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`.
+# @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

@@ -1,55 +1,36 @@
 import type { Controller } from "./controller.js";
 import type { Model } from "./models/profile.js";
-import type { Scope, InterruptRecord } from "./state/schema.js";
-import { type Stream, type DeliveryTarget, type Attachment } from "./engine/delivery.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, type JsonValue } from "./json.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 type { ModelRef } from "./models/contract.js";
-import { PluginHost } from "./plugins/host.js";
-import type { RegistryLease } from "./plugins/registry.js";
-import { PluginStateAccess } from "./state/plugin-state.js";
-import type { StorageBackend, Lease } from "./state/storage-ports.js";
-import type { Checkpoint, RecordEntry, StreamLimits } from "./state/schema.js";
-import type { StreamRecord } from "./trace/records.js";
-export interface ExecutionOrigin {
-    parentStreamId: string;
-    parentToolExecutionId?: string;
-    dispatchId: string;
-}
-export type ExecutionRequest = ({
-    kind: "input";
-    threadId: string;
-    input: readonly MessageData[];
-    model: ModelRef;
-    origin?: ExecutionOrigin;
-    context?: JsonObject;
-    limits?: Partial<StreamLimits>;
-} | {
-    kind: "resume";
-    threadId: string;
-    interruptId: string;
-    value: JsonValue;
-    model?: ModelRef;
-} | {
-    kind: "recover";
-    threadId: string;
-    streamId: string;
-    model?: ModelRef;
-}) & {
-    signal?: AbortSignal;
-};
-export interface AgentOptions {
+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?: Model | ModelRef;
+    model: M;
     instructions?: string | Instruction;
     limits?: Partial<StreamLimits>;
+    tools?: AgentTools;
+}
+export interface AgentTools {
+    concurrency?: number;
+    readonly [alias: string]: Tool | number | undefined;
 }
-export interface AgentExecutionOptions {
-    input: MessageData | readonly MessageData[];
-    model?: Model | ModelRef;
+export interface AgentExecutionOptions<M = ModelAdapter> {
+    model?: M | Model | ModelRef | string;
+    modelOptions?: ModelOptions<M>;
     scope?: Scope;
     context?: JsonObject;
     signal?: AbortSignal;
@@ -65,26 +46,11 @@ export interface GenerateOutcome {
     error: ErrorInfo | null;
 }
 export declare function inputMessages(input: MessageData | readonly MessageData[]): readonly MessageData[];
-export interface ExecutionFrame {
-    effectLocks?: Map<string, Promise<unknown>>;
-    commitQueue?: Promise<void>;
-    currentToolExecutionId?: string;
-    heartbeat?: ReturnType<typeof setInterval>;
-    ownershipError?: ErrorInfo;
-    request: ExecutionRequest;
-    sink: Attachment;
-    registry: RegistryLease;
-    lease: Lease;
-    cp: Checkpoint;
-    stream: StreamRecord;
-    records: Map<string, RecordEntry>;
-    state: PluginStateAccess;
-    admitted: boolean;
-    sequence: number;
-}
-export declare class Agent {
+export declare class Agent<M extends ModelSelection = ModelSelection> {
     readonly id: string;
-    readonly model: Readonly<ModelRef> | undefined;
+    readonly tools: readonly Tool[];
+    /** @internal */ readonly toolConcurrency: number;
+    readonly model: M;
     private controller?;
     /** @internal */ attachController(controller: Controller): void;
     private runtime;
@@ -95,34 +61,18 @@ export declare class Agent {
     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);
-    stream(options: AgentExecutionOptions): Stream;
-    generate(options: AgentExecutionOptions): Promise<GenerateOutcome>;
+    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>): Stream;
-    private execute;
-    private eventContext;
-    private watchLease;
-    private hook;
-    private put;
-    private rows;
-    private services;
-    private auxiliary;
-    private updateUsage;
-    private commit;
-    private commitNow;
-    private prepareMessage;
-    private appendMessage;
-    private loop;
-    private restoreFrame;
-    private prepareRecovery;
-    private suspend;
-    private prepareResume;
-    private prepareResumeFrame;
-    private finish;
-    cancel(threadId: string, streamId: string, reason?: string, target?: DeliveryTarget): Promise<void>;
+    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>;
 }