@tessar/core 0.0.0-stage → 0.1.0-alpha.0

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @tessar/core
 
-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'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`.

package/dist/agent.d.ts

@@ -0,0 +1,128 @@
+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";
+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 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 {
+    id: string;
+    model?: Model | ModelRef;
+    instructions?: string | Instruction;
+    limits?: Partial<StreamLimits>;
+}
+export interface AgentExecutionOptions {
+    input: MessageData | readonly MessageData[];
+    model?: Model | ModelRef;
+    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 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 {
+    readonly id: string;
+    readonly model: Readonly<ModelRef> | undefined;
+    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 active;
+    private closed;
+    private readonly resumeAdmissions;
+    constructor(options: AgentOptions);
+    stream(options: AgentExecutionOptions): Stream;
+    generate(options: AgentExecutionOptions): 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>;
+    shutdown(): Promise<void>;
+}