@smooai/smooth-operator-core 0.1.0

package/dist/cast.js

@@ -0,0 +1,103 @@
+/**
+ * Multi-agent cast: roles and per-role tool-access policy.
+ *
+ * Phase-2 sibling of the C# reference (`dotnet/core/src/Cast.cs`) and the Rust
+ * engine. A *cast* is the set of named roles a lead can dispatch to; each role has
+ * a {@link RoleKind} (Lead / Sidekick / Shadow) and a {@link Clearance} that gates
+ * which tools it may call.
+ *
+ * {@link Clearance} semantics (mirrors the reference engines):
+ * - a **deny always wins** — a denied tool is never permitted;
+ * - a **non-empty allow-list is a whitelist** — only listed tools are permitted;
+ * - **empty allow + empty deny means "all tools"**.
+ *
+ * Clearance is wired into the agent loop: if `AgentOptions.clearance` forbids a
+ * tool the model asked for, that tool is *not* executed — a clear "not permitted"
+ * result is returned to the model instead, mirroring how the engine surfaces other
+ * tool errors.
+ */
+/** A role's place in a multi-agent cast. Mirrors the reference engines' `RoleKind`. */
+export var RoleKind;
+(function (RoleKind) {
+    /** The orchestrator that delegates to sidekicks. */
+    RoleKind["Lead"] = "lead";
+    /** A focused specialist a lead can dispatch a sub-task to. */
+    RoleKind["Sidekick"] = "sidekick";
+    /** A passive observer (e.g. for logging/critique); not directly dispatchable. */
+    RoleKind["Shadow"] = "shadow";
+})(RoleKind || (RoleKind = {}));
+/**
+ * Tool-access policy for a role. A deny always wins; a non-empty `allowTools` is a
+ * whitelist; empty allow + empty deny means "all tools". `denyEverything` blocks
+ * every tool regardless of the lists.
+ */
+export class Clearance {
+    allowTools;
+    denyTools;
+    denyEverything;
+    constructor(options = {}) {
+        this.allowTools = new Set(options.allowTools ?? []);
+        this.denyTools = new Set(options.denyTools ?? []);
+        this.denyEverything = options.denyEverything ?? false;
+    }
+    static allowAll() {
+        return new Clearance();
+    }
+    static denyAll() {
+        return new Clearance({ denyEverything: true });
+    }
+    static allow(...tools) {
+        return new Clearance({ allowTools: tools });
+    }
+    static deny(...tools) {
+        return new Clearance({ denyTools: tools });
+    }
+    /** Whether `tool` is permitted under this clearance. */
+    isAllowed(tool) {
+        if (this.denyEverything)
+            return false;
+        if (this.denyTools.has(tool))
+            return false;
+        if (this.allowTools.size > 0)
+            return this.allowTools.has(tool);
+        return true;
+    }
+}
+/** Build an {@link OperatorRole} with the reference-engine defaults applied. */
+export function makeRole(name, kind, overrides = {}) {
+    return {
+        name,
+        kind,
+        instructions: overrides.instructions ?? '',
+        permissions: overrides.permissions ?? Clearance.allowAll(),
+        maxIterations: overrides.maxIterations ?? 8,
+        hidden: overrides.hidden ?? false,
+    };
+}
+/** The registered set of roles a lead can dispatch to. Mirrors the reference engines' `Cast`. */
+export class Cast {
+    roles = new Map();
+    register(role) {
+        this.roles.set(role.name, role);
+        return this;
+    }
+    get(name) {
+        return this.roles.get(name);
+    }
+    list() {
+        return [...this.roles.values()];
+    }
+    listVisible() {
+        return this.list().filter((r) => !r.hidden);
+    }
+    sidekicks() {
+        return this.list().filter((r) => r.kind === RoleKind.Sidekick);
+    }
+    get count() {
+        return this.roles.size;
+    }
+    get isEmpty() {
+        return this.roles.size === 0;
+    }
+}
+//# sourceMappingURL=cast.js.map

package/dist/cast.js.map

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

package/dist/checkpoint.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Conversation checkpointing — persist a turn's state so it can resume.
+ *
+ * Phase-1 sibling of the reference engines' checkpointing. A `CheckpointStore`
+ * saves and loads the conversation (the non-system messages) keyed by a
+ * conversation id, so a later turn — even in a new process — can pick up where
+ * the last left off. `InMemoryCheckpointStore` is the zero-dependency default.
+ */
+type Message = Record<string, unknown>;
+export interface Checkpoint {
+    conversationId: string;
+    messages: Message[];
+}
+export interface CheckpointStore {
+    save(checkpoint: Checkpoint): void;
+    load(conversationId: string): Checkpoint | undefined;
+}
+/** A process-local checkpoint store backed by a Map. */
+export declare class InMemoryCheckpointStore implements CheckpointStore {
+    private readonly store;
+    save(checkpoint: Checkpoint): void;
+    load(conversationId: string): Checkpoint | undefined;
+}
+export {};
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../src/checkpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,KAAK,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEvC,MAAM,WAAW,UAAU;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC5B,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACnC,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;CACxD;AAED,wDAAwD;AACxD,qBAAa,uBAAwB,YAAW,eAAe;IAC3D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IAEvD,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI;IAQlC,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;CAGvD"}

package/dist/checkpoint.js

@@ -0,0 +1,23 @@
+/**
+ * Conversation checkpointing — persist a turn's state so it can resume.
+ *
+ * Phase-1 sibling of the reference engines' checkpointing. A `CheckpointStore`
+ * saves and loads the conversation (the non-system messages) keyed by a
+ * conversation id, so a later turn — even in a new process — can pick up where
+ * the last left off. `InMemoryCheckpointStore` is the zero-dependency default.
+ */
+/** A process-local checkpoint store backed by a Map. */
+export class InMemoryCheckpointStore {
+    store = new Map();
+    save(checkpoint) {
+        // Copy the messages so later mutation of the live list doesn't bleed in.
+        this.store.set(checkpoint.conversationId, {
+            conversationId: checkpoint.conversationId,
+            messages: checkpoint.messages.map((m) => ({ ...m })),
+        });
+    }
+    load(conversationId) {
+        return this.store.get(conversationId);
+    }
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../src/checkpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAcH,wDAAwD;AACxD,MAAM,OAAO,uBAAuB;IACf,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IAEvD,IAAI,CAAC,UAAsB;QACvB,yEAAyE;QACzE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,cAAc,EAAE;YACtC,cAAc,EAAE,UAAU,CAAC,cAAc;YACzC,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;SACvD,CAAC,CAAC;IACP,CAAC;IAED,IAAI,CAAC,cAAsB;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC1C,CAAC;CACJ"}

package/dist/compaction.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Token-aware conversation compaction (sliding window).
+ *
+ * Phase-1 sibling of the reference engines' compaction. When a conversation's
+ * estimated token count exceeds a budget, drop the oldest non-system messages
+ * (keeping the system prompt and most recent turns) so the next model call stays
+ * within context. A coarse char/4 token estimate is used.
+ *
+ * Safety: the kept window never *starts* on a `tool` message (which would orphan
+ * a tool result whose preceding `assistant` tool_call was trimmed).
+ */
+type Message = Record<string, unknown>;
+export declare function estimateTokens(message: Message): number;
+/**
+ * Return `messages` trimmed to roughly `maxTokens`, preserving system messages
+ * and the most recent turns. Returns the input unchanged when already within
+ * budget or when `maxTokens` is non-positive (disabled).
+ */
+export declare function compact(messages: Message[], maxTokens: number): Message[];
+export {};
+//# sourceMappingURL=compaction.d.ts.map

package/dist/compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../src/compaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,KAAK,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEvC,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAOvD;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,EAAE,CAwBzE"}

package/dist/compaction.js

@@ -0,0 +1,50 @@
+/**
+ * Token-aware conversation compaction (sliding window).
+ *
+ * Phase-1 sibling of the reference engines' compaction. When a conversation's
+ * estimated token count exceeds a budget, drop the oldest non-system messages
+ * (keeping the system prompt and most recent turns) so the next model call stays
+ * within context. A coarse char/4 token estimate is used.
+ *
+ * Safety: the kept window never *starts* on a `tool` message (which would orphan
+ * a tool result whose preceding `assistant` tool_call was trimmed).
+ */
+const CHARS_PER_TOKEN = 4;
+export function estimateTokens(message) {
+    let text = typeof message.content === 'string' ? message.content : '';
+    const toolCalls = message.tool_calls ?? [];
+    for (const tc of toolCalls) {
+        text += String(tc.function?.name ?? '') + String(tc.function?.arguments ?? '');
+    }
+    return Math.max(1, Math.ceil(text.length / CHARS_PER_TOKEN));
+}
+/**
+ * Return `messages` trimmed to roughly `maxTokens`, preserving system messages
+ * and the most recent turns. Returns the input unchanged when already within
+ * budget or when `maxTokens` is non-positive (disabled).
+ */
+export function compact(messages, maxTokens) {
+    if (maxTokens <= 0)
+        return messages;
+    const system = messages.filter((m) => m.role === 'system');
+    const rest = messages.filter((m) => m.role !== 'system');
+    const systemTokens = system.reduce((sum, m) => sum + estimateTokens(m), 0);
+    const total = systemTokens + rest.reduce((sum, m) => sum + estimateTokens(m), 0);
+    if (total <= maxTokens)
+        return messages;
+    const budget = maxTokens - systemTokens;
+    const kept = [];
+    let running = 0;
+    for (let i = rest.length - 1; i >= 0; i--) {
+        const t = estimateTokens(rest[i]);
+        if (running + t > budget && kept.length > 0)
+            break;
+        kept.unshift(rest[i]);
+        running += t;
+    }
+    // Never start the kept window on an orphaned tool result.
+    while (kept.length > 0 && kept[0].role === 'tool')
+        kept.shift();
+    return [...system, ...kept];
+}
+//# sourceMappingURL=compaction.js.map

package/dist/compaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.js","sourceRoot":"","sources":["../src/compaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,eAAe,GAAG,CAAC,CAAC;AAI1B,MAAM,UAAU,cAAc,CAAC,OAAgB;IAC3C,IAAI,IAAI,GAAG,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IACtE,MAAM,SAAS,GAAI,OAAO,CAAC,UAAsF,IAAI,EAAE,CAAC;IACxH,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QACzB,IAAI,IAAI,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,IAAI,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,IAAI,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,QAAmB,EAAE,SAAiB;IAC1D,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,QAAQ,CAAC;IAEpC,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IAC3D,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IAEzD,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3E,MAAM,KAAK,GAAG,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACjF,IAAI,KAAK,IAAI,SAAS;QAAE,OAAO,QAAQ,CAAC;IAExC,MAAM,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC;IACxC,MAAM,IAAI,GAAc,EAAE,CAAC;IAC3B,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,MAAM,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAClC,IAAI,OAAO,GAAG,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM;QACnD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACtB,OAAO,IAAI,CAAC,CAAC;IACjB,CAAC;IAED,0DAA0D;IAC1D,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM;QAAE,IAAI,CAAC,KAAK,EAAE,CAAC;IAEhE,OAAO,CAAC,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;AAChC,CAAC"}

package/dist/cost.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Token-usage accounting and budget enforcement.
+ *
+ * Phase-1 sibling of the reference engines' cost tracking. Accumulates token
+ * usage across a turn's model calls, optionally converts it to a USD cost via a
+ * per-model pricing table, and lets a turn stop early once a token or cost budget
+ * is hit. Usage is exact; cost depends on the (approximate, overridable) pricing.
+ */
+export interface Usage {
+    promptTokens: number;
+    completionTokens: number;
+}
+export declare function totalTokens(u: Usage): number;
+/** USD per 1,000,000 tokens, input and output. */
+export interface ModelPricing {
+    inputPerMTok: number;
+    outputPerMTok: number;
+}
+export declare function pricingCost(p: ModelPricing, u: Usage): number;
+/** Approximate default pricing (USD / 1M tokens). Override via AgentOptions.pricing. */
+export declare const DEFAULT_PRICING: Record<string, ModelPricing>;
+/** A ceiling for a turn. Either limit may be set; the first hit stops the turn. */
+export interface CostBudget {
+    maxUsd?: number;
+    maxTokens?: number;
+}
+/** Accumulates usage + cost across a turn's model calls. */
+export declare class CostTracker {
+    usage: Usage;
+    costUsd: number;
+    record(model: string, usage: Usage, pricing?: Record<string, ModelPricing>): void;
+    exceeds(budget?: CostBudget): boolean;
+}
+//# sourceMappingURL=cost.d.ts.map

package/dist/cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,KAAK;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM,CAE5C;AAED,kDAAkD;AAClD,MAAM,WAAW,YAAY;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,KAAK,GAAG,MAAM,CAE7D;AAED,wFAAwF;AACxF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAGxD,CAAC;AAEF,mFAAmF;AACnF,MAAM,WAAW,UAAU;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,4DAA4D;AAC5D,qBAAa,WAAW;IACpB,KAAK,EAAE,KAAK,CAA4C;IACxD,OAAO,SAAK;IAEZ,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,IAAI;IAQjF,OAAO,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO;CAMxC"}

package/dist/cost.js

@@ -0,0 +1,42 @@
+/**
+ * Token-usage accounting and budget enforcement.
+ *
+ * Phase-1 sibling of the reference engines' cost tracking. Accumulates token
+ * usage across a turn's model calls, optionally converts it to a USD cost via a
+ * per-model pricing table, and lets a turn stop early once a token or cost budget
+ * is hit. Usage is exact; cost depends on the (approximate, overridable) pricing.
+ */
+export function totalTokens(u) {
+    return u.promptTokens + u.completionTokens;
+}
+export function pricingCost(p, u) {
+    return (u.promptTokens * p.inputPerMTok + u.completionTokens * p.outputPerMTok) / 1_000_000;
+}
+/** Approximate default pricing (USD / 1M tokens). Override via AgentOptions.pricing. */
+export const DEFAULT_PRICING = {
+    'claude-haiku-4-5': { inputPerMTok: 1.0, outputPerMTok: 5.0 },
+    'claude-sonnet-4-5': { inputPerMTok: 3.0, outputPerMTok: 15.0 },
+};
+/** Accumulates usage + cost across a turn's model calls. */
+export class CostTracker {
+    usage = { promptTokens: 0, completionTokens: 0 };
+    costUsd = 0;
+    record(model, usage, pricing) {
+        this.usage.promptTokens += usage.promptTokens;
+        this.usage.completionTokens += usage.completionTokens;
+        const table = pricing ?? DEFAULT_PRICING;
+        const mp = table[model];
+        if (mp)
+            this.costUsd += pricingCost(mp, usage);
+    }
+    exceeds(budget) {
+        if (!budget)
+            return false;
+        if (budget.maxTokens !== undefined && totalTokens(this.usage) >= budget.maxTokens)
+            return true;
+        if (budget.maxUsd !== undefined && this.costUsd >= budget.maxUsd)
+            return true;
+        return false;
+    }
+}
+//# sourceMappingURL=cost.js.map

package/dist/cost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.js","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,MAAM,UAAU,WAAW,CAAC,CAAQ;IAChC,OAAO,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,gBAAgB,CAAC;AAC/C,CAAC;AAQD,MAAM,UAAU,WAAW,CAAC,CAAe,EAAE,CAAQ;IACjD,OAAO,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,gBAAgB,GAAG,CAAC,CAAC,aAAa,CAAC,GAAG,SAAS,CAAC;AAChG,CAAC;AAED,wFAAwF;AACxF,MAAM,CAAC,MAAM,eAAe,GAAiC;IACzD,kBAAkB,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE;IAC7D,mBAAmB,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE;CAClE,CAAC;AAQF,4DAA4D;AAC5D,MAAM,OAAO,WAAW;IACpB,KAAK,GAAU,EAAE,YAAY,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,CAAC;IACxD,OAAO,GAAG,CAAC,CAAC;IAEZ,MAAM,CAAC,KAAa,EAAE,KAAY,EAAE,OAAsC;QACtE,IAAI,CAAC,KAAK,CAAC,YAAY,IAAI,KAAK,CAAC,YAAY,CAAC;QAC9C,IAAI,CAAC,KAAK,CAAC,gBAAgB,IAAI,KAAK,CAAC,gBAAgB,CAAC;QACtD,MAAM,KAAK,GAAG,OAAO,IAAI,eAAe,CAAC;QACzC,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,EAAE;YAAE,IAAI,CAAC,OAAO,IAAI,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACnD,CAAC;IAED,OAAO,CAAC,MAAmB;QACvB,IAAI,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QAC1B,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC;QAC/F,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QAC9E,OAAO,KAAK,CAAC;IACjB,CAAC;CACJ"}

package/dist/humanGate.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Human-in-the-loop approval — pause before a sensitive/write tool runs.
+ *
+ * Phase-2 sibling of the C# `HumanGate` (`dotnet/core`) and the Rust engine's
+ * confirmation hook. When a turn is about to run a tool the caller flagged as
+ * needing approval, the agent consults a {@link HumanGate} first. The gate IS the
+ * pause point — a UI gate awaits a real person (e.g. resolving a promise when a
+ * button is clicked); a programmatic gate decides immediately. A denial is never
+ * executed; the denial reason is fed back to the model as the tool result so the
+ * model can adapt. With no gate configured, behavior is unchanged.
+ */
+/** The human's verdict on a tool call that required approval. */
+export declare enum HumanDecision {
+    Approved = "approved",
+    Denied = "denied"
+}
+/**
+ * A request for human approval before the agent executes a sensitive/write tool.
+ * Mirrors the C# `HumanApprovalRequest` / the Rust engine's `HumanRequest::Confirm`.
+ */
+export interface HumanApprovalRequest {
+    toolName: string;
+    arguments: Record<string, unknown>;
+    prompt: string;
+}
+/** The response to a {@link HumanApprovalRequest}. Mirrors the C# `HumanApprovalResponse`. */
+export interface HumanApprovalResponse {
+    decision: HumanDecision;
+    reason?: string;
+}
+/** True when the decision is {@link HumanDecision.Approved}. */
+export declare function isApproved(response: HumanApprovalResponse): boolean;
+/** Build an approval. */
+export declare function approve(): HumanApprovalResponse;
+/** Build a denial carrying a reason the model will see. */
+export declare function deny(reason: string): HumanApprovalResponse;
+/**
+ * The human-in-the-loop seam: the agent consults it before running any tool that
+ * {@link AgentOptions.requiresApproval} flags. The implementation IS the pause
+ * point — wire it to a UI awaiting a real person, or decide programmatically.
+ * Mirrors the C# `IHumanGate` (here just an async function, the idiomatic TS seam).
+ */
+export type HumanGate = (request: HumanApprovalRequest) => Promise<HumanApprovalResponse>;
+//# sourceMappingURL=humanGate.d.ts.map

package/dist/humanGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"humanGate.d.ts","sourceRoot":"","sources":["../src/humanGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,iEAAiE;AACjE,oBAAY,aAAa;IACrB,QAAQ,aAAa;IACrB,MAAM,WAAW;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,8FAA8F;AAC9F,MAAM,WAAW,qBAAqB;IAClC,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,QAAQ,EAAE,qBAAqB,GAAG,OAAO,CAEnE;AAED,yBAAyB;AACzB,wBAAgB,OAAO,IAAI,qBAAqB,CAE/C;AAED,2DAA2D;AAC3D,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,qBAAqB,CAE1D;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC"}

package/dist/humanGate.js

@@ -0,0 +1,30 @@
+/**
+ * Human-in-the-loop approval — pause before a sensitive/write tool runs.
+ *
+ * Phase-2 sibling of the C# `HumanGate` (`dotnet/core`) and the Rust engine's
+ * confirmation hook. When a turn is about to run a tool the caller flagged as
+ * needing approval, the agent consults a {@link HumanGate} first. The gate IS the
+ * pause point — a UI gate awaits a real person (e.g. resolving a promise when a
+ * button is clicked); a programmatic gate decides immediately. A denial is never
+ * executed; the denial reason is fed back to the model as the tool result so the
+ * model can adapt. With no gate configured, behavior is unchanged.
+ */
+/** The human's verdict on a tool call that required approval. */
+export var HumanDecision;
+(function (HumanDecision) {
+    HumanDecision["Approved"] = "approved";
+    HumanDecision["Denied"] = "denied";
+})(HumanDecision || (HumanDecision = {}));
+/** True when the decision is {@link HumanDecision.Approved}. */
+export function isApproved(response) {
+    return response.decision === HumanDecision.Approved;
+}
+/** Build an approval. */
+export function approve() {
+    return { decision: HumanDecision.Approved };
+}
+/** Build a denial carrying a reason the model will see. */
+export function deny(reason) {
+    return { decision: HumanDecision.Denied, reason };
+}
+//# sourceMappingURL=humanGate.js.map

package/dist/humanGate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"humanGate.js","sourceRoot":"","sources":["../src/humanGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,iEAAiE;AACjE,MAAM,CAAN,IAAY,aAGX;AAHD,WAAY,aAAa;IACrB,sCAAqB,CAAA;IACrB,kCAAiB,CAAA;AACrB,CAAC,EAHW,aAAa,KAAb,aAAa,QAGxB;AAkBD,gEAAgE;AAChE,MAAM,UAAU,UAAU,CAAC,QAA+B;IACtD,OAAO,QAAQ,CAAC,QAAQ,KAAK,aAAa,CAAC,QAAQ,CAAC;AACxD,CAAC;AAED,yBAAyB;AACzB,MAAM,UAAU,OAAO;IACnB,OAAO,EAAE,QAAQ,EAAE,aAAa,CAAC,QAAQ,EAAE,CAAC;AAChD,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,IAAI,CAAC,MAAc;IAC/B,OAAO,EAAE,QAAQ,EAAE,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;AACtD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @smooai/smooth-operator-core — a native, in-process agent engine for TypeScript.
+ *
+ * The Phase-0 TypeScript sibling of the Rust reference engine, the C# core, and
+ * the Python core: an agentic tool-calling loop over any OpenAI-compatible chat
+ * client, with in-memory knowledge grounding. See `docs/Architecture/TypeScript Core.md`.
+ */
+export { delegateTool, SmoothAgent } from './agent.js';
+export type { AgentOptions, AgentRunResponse, ChatChunk, ChatClientLike, StreamEvent, Tool } from './agent.js';
+export { Cast, Clearance, makeRole, RoleKind } from './cast.js';
+export type { OperatorRole } from './cast.js';
+export { InMemoryCheckpointStore } from './checkpoint.js';
+export type { Checkpoint, CheckpointStore } from './checkpoint.js';
+export { CostTracker, DEFAULT_PRICING } from './cost.js';
+export type { CostBudget, ModelPricing, Usage } from './cost.js';
+export { approve, deny, HumanDecision, isApproved } from './humanGate.js';
+export type { HumanApprovalRequest, HumanApprovalResponse, HumanGate } from './humanGate.js';
+export { InMemoryKnowledge } from './knowledge.js';
+export type { Knowledge, KnowledgeHit } from './knowledge.js';
+export { MockLlmProvider, textResponse, toolCallResponse } from './llmProvider.js';
+export type { LlmProvider, RecordedCall, ScriptedMessage, ScriptedUsage } from './llmProvider.js';
+export { InMemoryMemory } from './memory.js';
+export type { Memory, MemoryEntry } from './memory.js';
+export { LexicalReranker, NoopReranker } from './rerank.js';
+export type { Reranker } from './rerank.js';
+export { SmoothAgentThread } from './thread.js';
+export { MAX_MATCHES, TOOL_SEARCH_NAME, ToolSearch } from './toolSearch.js';
+export { HashEmbedder, hashToken, VectorKnowledge } from './vector.js';
+export type { Embedder } from './vector.js';
+export { END, Workflow, WorkflowError } from './workflow.js';
+export type { NodeFn, Router } from './workflow.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAC/G,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAChE,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACzD,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC1E,YAAY,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC7F,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACnF,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAClG,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC5D,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACvE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * @smooai/smooth-operator-core — a native, in-process agent engine for TypeScript.
+ *
+ * The Phase-0 TypeScript sibling of the Rust reference engine, the C# core, and
+ * the Python core: an agentic tool-calling loop over any OpenAI-compatible chat
+ * client, with in-memory knowledge grounding. See `docs/Architecture/TypeScript Core.md`.
+ */
+export { delegateTool, SmoothAgent } from './agent.js';
+export { Cast, Clearance, makeRole, RoleKind } from './cast.js';
+export { InMemoryCheckpointStore } from './checkpoint.js';
+export { CostTracker, DEFAULT_PRICING } from './cost.js';
+export { approve, deny, HumanDecision, isApproved } from './humanGate.js';
+export { InMemoryKnowledge } from './knowledge.js';
+export { MockLlmProvider, textResponse, toolCallResponse } from './llmProvider.js';
+export { InMemoryMemory } from './memory.js';
+export { LexicalReranker, NoopReranker } from './rerank.js';
+export { SmoothAgentThread } from './thread.js';
+export { MAX_MATCHES, TOOL_SEARCH_NAME, ToolSearch } from './toolSearch.js';
+export { HashEmbedder, hashToken, VectorKnowledge } from './vector.js';
+export { END, Workflow, WorkflowError } from './workflow.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEhE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEzD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEnF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEvE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/knowledge.d.ts

@@ -0,0 +1,30 @@
+/**
+ * In-memory knowledge base for the TypeScript smooth-operator core.
+ *
+ * A minimal lexical-overlap retriever — the Phase-0 sibling of the Rust engine's
+ * in-memory lexical store and the Python core's `InMemoryKnowledge`. Documents
+ * are scored by token overlap with the query; the top-k are returned. When
+ * nothing overlaps, the first k documents are returned anyway so the agent still
+ * has context to ground (or honestly decline) against.
+ */
+export interface KnowledgeHit {
+    content: string;
+    source: string;
+    score: number;
+}
+/**
+ * A retriever: returns the most relevant documents for a query. Both the lexical
+ * {@link InMemoryKnowledge} and the embedding-backed `VectorKnowledge` satisfy
+ * this, so the agent accepts either.
+ */
+export interface Knowledge {
+    query(query: string, topK?: number): KnowledgeHit[];
+}
+export declare class InMemoryKnowledge {
+    private readonly docs;
+    /** Add a document to the knowledge base. */
+    ingest(content: string, source: string): void;
+    /** Return up to `topK` documents, ranked by token overlap with `query`. */
+    query(query: string, topK?: number): KnowledgeHit[];
+}
+//# sourceMappingURL=knowledge.d.ts.map

package/dist/knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../src/knowledge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACtB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;CACvD;AAWD,qBAAa,iBAAiB;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAElC,4CAA4C;IAC5C,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAI7C,2EAA2E;IAC3E,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,SAAI,GAAG,YAAY,EAAE;CAsBjD"}

package/dist/knowledge.js

@@ -0,0 +1,43 @@
+/**
+ * In-memory knowledge base for the TypeScript smooth-operator core.
+ *
+ * A minimal lexical-overlap retriever — the Phase-0 sibling of the Rust engine's
+ * in-memory lexical store and the Python core's `InMemoryKnowledge`. Documents
+ * are scored by token overlap with the query; the top-k are returned. When
+ * nothing overlaps, the first k documents are returned anyway so the agent still
+ * has context to ground (or honestly decline) against.
+ */
+function tokenize(text) {
+    return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+}
+export class InMemoryKnowledge {
+    docs = [];
+    /** Add a document to the knowledge base. */
+    ingest(content, source) {
+        this.docs.push({ content, source });
+    }
+    /** Return up to `topK` documents, ranked by token overlap with `query`. */
+    query(query, topK = 4) {
+        const qTokens = new Set(tokenize(query));
+        const scored = this.docs.map((doc) => {
+            const docTokens = new Set(tokenize(doc.content));
+            let overlap = 0;
+            for (const t of docTokens)
+                if (qTokens.has(t))
+                    overlap++;
+            return { overlap, doc };
+        });
+        scored.sort((a, b) => b.overlap - a.overlap);
+        const hits = scored
+            .slice(0, topK)
+            .filter((s) => s.overlap > 0)
+            .map((s) => ({ content: s.doc.content, source: s.doc.source, score: s.overlap }));
+        if (hits.length === 0) {
+            // No lexical overlap — still hand the model the first k docs so it can
+            // ground or honestly decline, rather than retrieving nothing.
+            return this.docs.slice(0, topK).map((doc) => ({ content: doc.content, source: doc.source, score: 0 }));
+        }
+        return hits;
+    }
+}
+//# sourceMappingURL=knowledge.js.map

package/dist/knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.js","sourceRoot":"","sources":["../src/knowledge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAsBH,SAAS,QAAQ,CAAC,IAAY;IAC1B,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;AACxD,CAAC;AAED,MAAM,OAAO,iBAAiB;IACT,IAAI,GAAU,EAAE,CAAC;IAElC,4CAA4C;IAC5C,MAAM,CAAC,OAAe,EAAE,MAAc;QAClC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,2EAA2E;IAC3E,KAAK,CAAC,KAAa,EAAE,IAAI,GAAG,CAAC;QACzB,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;QACzC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;YACjC,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YACjD,IAAI,OAAO,GAAG,CAAC,CAAC;YAChB,KAAK,MAAM,CAAC,IAAI,SAAS;gBAAE,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;oBAAE,OAAO,EAAE,CAAC;YACzD,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;QAC5B,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;QAE7C,MAAM,IAAI,GAAG,MAAM;aACd,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC;aACd,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC;aAC5B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAEtF,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpB,uEAAuE;YACvE,8DAA8D;YAC9D,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAC3G,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;CACJ"}