@smooai/smooth-operator-core 0.1.0

package/dist/toolSearch.js

@@ -0,0 +1,110 @@
+/**
+ * The `tool_search` meta-tool — promotes deferred tools on demand.
+ *
+ * Phase-3 sibling of the Rust reference `tool_search.rs`. Mirrors the behaviour,
+ * not the type shapes (this core has no `ToolRegistry` — tools are a plain array
+ * on {@link AgentOptions}).
+ *
+ * As a tool set grows past ~20-30 entries, every model turn pays tokens to read
+ * schemas it isn't going to use, diluting the model's attention budget. So a caller
+ * can register some tools as **deferred** (`AgentOptions.deferredTools`): their
+ * schemas are hidden from the model. Instead the agent advertises a single built-in
+ * `tool_search(query)` meta-tool. When the model calls it, this fuzzy-matches the
+ * query against the deferred tools' names + descriptions, **promotes** the matches
+ * into the visible set (so the model can call them on subsequent turns), and returns
+ * each match's name + description as JSON.
+ *
+ * A deferred tool that has not been promoted is *not* dispatchable — calling it
+ * surfaces as an unknown tool until `tool_search` adds it to the promoted set.
+ */
+/** The built-in meta-tool's name. Reserved when deferred tools are in play. */
+export const TOOL_SEARCH_NAME = 'tool_search';
+/**
+ * Cap on how many deferred tools a single `tool_search` call may promote, so a
+ * generic query like "tool" doesn't promote the entire deferred set in one shot.
+ */
+export const MAX_MATCHES = 8;
+const SCHEMA = {
+    type: 'object',
+    properties: {
+        query: {
+            type: 'string',
+            description: 'Keyword to match against deferred tool names and descriptions. Case-insensitive substring match.',
+        },
+    },
+    required: ['query'],
+};
+const DESCRIPTION = 'Search for additional tools by keyword. Returns matching tool schemas as JSON; ' +
+    'matched tools become available on subsequent turns. Use when you think a tool ' +
+    "exists for a specific task but isn't in your current tool list — e.g. " +
+    'tool_search(query="git") or tool_search(query="http request").';
+/**
+ * Drives deferred-tool promotion for one agent run. Implements {@link Tool} so the
+ * agent can advertise + dispatch it like any other tool. Holds the deferred tools
+ * (by name) and the mutable set of promoted names; the agent consults
+ * {@link promotedTools} each iteration to decide which deferred schemas are now
+ * visible/dispatchable.
+ */
+export class ToolSearch {
+    name = TOOL_SEARCH_NAME;
+    description = DESCRIPTION;
+    parameters = SCHEMA;
+    deferredByName;
+    promoted = new Set();
+    constructor(deferred) {
+        this.deferredByName = new Map(deferred.map((t) => [t.name, t]));
+    }
+    /** True if any tool was registered deferred (the meta-tool is advertised only then). */
+    hasDeferred() {
+        return this.deferredByName.size > 0;
+    }
+    /** True if a deferred tool has been promoted and is now dispatchable. */
+    isPromoted(name) {
+        return this.promoted.has(name);
+    }
+    /** The deferred tools that have been promoted — their schemas join the visible set. */
+    promotedTools() {
+        const out = [];
+        for (const n of this.promoted) {
+            const t = this.deferredByName.get(n);
+            if (t)
+                out.push(t);
+        }
+        return out;
+    }
+    /** Resolve a promoted deferred tool for dispatch. Unpromoted deferred tools are invisible. */
+    toolByName(name) {
+        return this.promoted.has(name) ? this.deferredByName.get(name) : undefined;
+    }
+    /** Mark a deferred tool promoted. Returns false if no such deferred tool. */
+    promote(name) {
+        if (!this.deferredByName.has(name))
+            return false;
+        this.promoted.add(name);
+        return true;
+    }
+    /** Fuzzy-match the query, promote matches, and return their schemas as JSON. */
+    async execute(args) {
+        const query = args.query;
+        if (typeof query !== 'string') {
+            return JSON.stringify({ matched: 0, tools: [], note: 'missing required `query` parameter' });
+        }
+        const needle = query.trim().toLowerCase();
+        if (needle.length === 0) {
+            return JSON.stringify({ matched: 0, tools: [], note: 'empty query — pass a keyword like "git" or "network"' });
+        }
+        const matched = [];
+        for (const t of this.deferredByName.values()) {
+            if (t.name.toLowerCase().includes(needle) || t.description.toLowerCase().includes(needle)) {
+                matched.push(t);
+                if (matched.length >= MAX_MATCHES)
+                    break;
+            }
+        }
+        for (const t of matched)
+            this.promoted.add(t.name);
+        const tools = matched.map((t) => ({ name: t.name, description: t.description, parameters: t.parameters }));
+        return JSON.stringify({ matched: tools.length, tools });
+    }
+}
+//# sourceMappingURL=toolSearch.js.map

package/dist/toolSearch.js.map

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

package/dist/vector.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Vector knowledge — embedding-backed semantic retrieval.
+ *
+ * Phase-1 sibling of the reference engines' vector store. `VectorKnowledge` embeds
+ * documents and queries and retrieves by cosine similarity, satisfying the same
+ * {@link Knowledge} interface as the lexical retriever (so the agent accepts
+ * either). The `Embedder` is pluggable: the default `HashEmbedder` is deterministic
+ * and offline (feature-hashed bag-of-words) — good for tests and a zero-dependency
+ * default — while a gateway embedder drops in behind the same interface for true
+ * semantics.
+ */
+import type { Knowledge, KnowledgeHit } from './knowledge.js';
+/** A small deterministic non-cryptographic hash (FNV-1a, 32-bit). */
+export declare function hashToken(token: string): number;
+export interface Embedder {
+    embed(text: string): number[];
+}
+/**
+ * Deterministic, offline feature-hashing embedder. Hashes each token into one of
+ * `dim` buckets (signed) and L2-normalizes. No learned semantics, but a real
+ * vector with cosine geometry — docs sharing tokens land near each other.
+ */
+export declare class HashEmbedder implements Embedder {
+    private readonly dim;
+    constructor(dim?: number);
+    embed(text: string): number[];
+}
+/** An embedding-backed knowledge store with cosine-similarity retrieval. */
+export declare class VectorKnowledge implements Knowledge {
+    private readonly embedder;
+    private readonly docs;
+    constructor(embedder?: Embedder);
+    ingest(content: string, source: string): void;
+    query(query: string, topK?: number): KnowledgeHit[];
+}
+//# sourceMappingURL=vector.d.ts.map

package/dist/vector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector.d.ts","sourceRoot":"","sources":["../src/vector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAM9D,qEAAqE;AACrE,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO/C;AAED,MAAM,WAAW,QAAQ;IACrB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACjC;AAED;;;;GAIG;AACH,qBAAa,YAAa,YAAW,QAAQ;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,SAAM;IAItC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;CAWhC;AAQD,4EAA4E;AAC5E,qBAAa,eAAgB,YAAW,SAAS;IAGjC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAFrC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiE;gBAEzD,QAAQ,GAAE,QAA6B;IAEpE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAI7C,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,SAAI,GAAG,YAAY,EAAE;CASjD"}

package/dist/vector.js

@@ -0,0 +1,75 @@
+/**
+ * Vector knowledge — embedding-backed semantic retrieval.
+ *
+ * Phase-1 sibling of the reference engines' vector store. `VectorKnowledge` embeds
+ * documents and queries and retrieves by cosine similarity, satisfying the same
+ * {@link Knowledge} interface as the lexical retriever (so the agent accepts
+ * either). The `Embedder` is pluggable: the default `HashEmbedder` is deterministic
+ * and offline (feature-hashed bag-of-words) — good for tests and a zero-dependency
+ * default — while a gateway embedder drops in behind the same interface for true
+ * semantics.
+ */
+function tokens(text) {
+    return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+}
+/** A small deterministic non-cryptographic hash (FNV-1a, 32-bit). */
+export function hashToken(token) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < token.length; i++) {
+        h ^= token.charCodeAt(i) & 0xff;
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h >>> 0;
+}
+/**
+ * Deterministic, offline feature-hashing embedder. Hashes each token into one of
+ * `dim` buckets (signed) and L2-normalizes. No learned semantics, but a real
+ * vector with cosine geometry — docs sharing tokens land near each other.
+ */
+export class HashEmbedder {
+    dim;
+    constructor(dim = 256) {
+        this.dim = dim;
+        if (dim <= 0)
+            throw new Error('dim must be positive');
+    }
+    embed(text) {
+        const vec = new Array(this.dim).fill(0);
+        for (const tok of tokens(text)) {
+            const h = hashToken(tok);
+            const bucket = h % this.dim;
+            const sign = (h >>> 31) & 1 ? -1 : 1;
+            vec[bucket] += sign;
+        }
+        const norm = Math.sqrt(vec.reduce((s, v) => s + v * v, 0));
+        return norm > 0 ? vec.map((v) => v / norm) : vec;
+    }
+}
+function cosine(a, b) {
+    let s = 0;
+    for (let i = 0; i < a.length; i++)
+        s += a[i] * b[i]; // both L2-normalized
+    return s;
+}
+/** An embedding-backed knowledge store with cosine-similarity retrieval. */
+export class VectorKnowledge {
+    embedder;
+    docs = [];
+    constructor(embedder = new HashEmbedder()) {
+        this.embedder = embedder;
+    }
+    ingest(content, source) {
+        this.docs.push({ emb: this.embedder.embed(content), content, source });
+    }
+    query(query, topK = 4) {
+        if (topK <= 0 || this.docs.length === 0)
+            return [];
+        const q = this.embedder.embed(query);
+        return this.docs
+            .map((d) => ({ content: d.content, source: d.source, score: cosine(q, d.emb) }))
+            .filter((h) => h.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, topK);
+    }
+}
+//# sourceMappingURL=vector.js.map

package/dist/vector.js.map

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

package/dist/workflow.d.ts

@@ -0,0 +1,62 @@
+/**
+ * LangGraph-inspired typed workflow graph with conditional edges.
+ *
+ * Phase-3 sibling of the reference engine's workflow primitive. A `Workflow<S>`
+ * is a state machine: **nodes** transform a typed state value and **edges** —
+ * static or **conditional** — determine the next node to execute. The runner
+ * starts at the entry node, applies each node then follows its outgoing edge,
+ * until it reaches the `END` sentinel (or a node with no outgoing edge), then
+ * returns the final state.
+ *
+ * Nodes may be sync or async; the runner awaits their results. A `maxSteps` cap
+ * bounds execution so an intentional or accidental cycle can't loop forever.
+ *
+ * Standalone module — it does not touch the agent loop. The point is the seam: a
+ * multi-step orchestration (parse → guardrails → retrieve → compose → …) drops in
+ * as a graph of named nodes with the routing made explicit.
+ */
+/** Sentinel a conditional router can return to signal termination. */
+export declare const END: "__end__";
+/** A node transforms state into a new state; may be sync or async. */
+export type NodeFn<S> = (state: S) => S | Promise<S>;
+/** A conditional router inspects state and returns the next node name (or `END`). */
+export type Router<S> = (state: S) => string;
+/** Thrown when a workflow is misconfigured or exceeds its step limit. */
+export declare class WorkflowError extends Error {
+    constructor(message: string);
+}
+/**
+ * A typed workflow graph: named nodes connected by static/conditional edges.
+ *
+ * Build with `addNode`, `addEdge` / `addConditionalEdge`, `setEntry`, and
+ * `setEnd`; the builder methods return `this` so they chain. `run` executes the
+ * graph from the entry node.
+ */
+export declare class Workflow<S> {
+    private readonly maxSteps;
+    private readonly nodes;
+    private readonly edges;
+    private entry;
+    constructor(maxSteps?: number);
+    /** Register a node `func` under `name` (used to reference it in edges). */
+    addNode(name: string, func: NodeFn<S>): this;
+    /** Add a static edge `from` → `to`. */
+    addEdge(from: string, to: string): this;
+    /**
+     * Add a conditional edge whose `router` picks the next node at runtime. The
+     * router returns the target node name, or `END` to terminate the workflow.
+     */
+    addConditionalEdge(from: string, router: Router<S>): this;
+    /** Set the entry node (first node to execute). */
+    setEntry(name: string): this;
+    /** Mark `from` as terminal — reaching it ends the workflow. */
+    setEnd(from: string): this;
+    /**
+     * Execute the workflow from the entry node, returning the final state.
+     *
+     * Throws {@link WorkflowError} if no entry node was set, a referenced node
+     * does not exist, or the `maxSteps` cap is exceeded (e.g. an unbroken cycle).
+     */
+    run(initialState: S): Promise<S>;
+}
+//# sourceMappingURL=workflow.d.ts.map

package/dist/workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../src/workflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,sEAAsE;AACtE,eAAO,MAAM,GAAG,EAAG,SAAkB,CAAC;AAEtC,sEAAsE;AACtE,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAErD,qFAAqF;AACrF,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;AAE7C,yEAAyE;AACzE,qBAAa,aAAc,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI9B;AAKD;;;;;;GAMG;AACH,qBAAa,QAAQ,CAAC,CAAC;IAKP,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IACpD,OAAO,CAAC,KAAK,CAAqB;gBAEL,QAAQ,SAAM;IAE3C,2EAA2E;IAC3E,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI;IAK5C,uCAAuC;IACvC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAKvC;;;OAGG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI;IAKzD,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK5B,+DAA+D;IAC/D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK1B;;;;;OAKG;IACG,GAAG,CAAC,YAAY,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAmCzC"}

package/dist/workflow.js

@@ -0,0 +1,109 @@
+/**
+ * LangGraph-inspired typed workflow graph with conditional edges.
+ *
+ * Phase-3 sibling of the reference engine's workflow primitive. A `Workflow<S>`
+ * is a state machine: **nodes** transform a typed state value and **edges** —
+ * static or **conditional** — determine the next node to execute. The runner
+ * starts at the entry node, applies each node then follows its outgoing edge,
+ * until it reaches the `END` sentinel (or a node with no outgoing edge), then
+ * returns the final state.
+ *
+ * Nodes may be sync or async; the runner awaits their results. A `maxSteps` cap
+ * bounds execution so an intentional or accidental cycle can't loop forever.
+ *
+ * Standalone module — it does not touch the agent loop. The point is the seam: a
+ * multi-step orchestration (parse → guardrails → retrieve → compose → …) drops in
+ * as a graph of named nodes with the routing made explicit.
+ */
+/** Sentinel a conditional router can return to signal termination. */
+export const END = '__end__';
+/** Thrown when a workflow is misconfigured or exceeds its step limit. */
+export class WorkflowError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WorkflowError';
+    }
+}
+/**
+ * A typed workflow graph: named nodes connected by static/conditional edges.
+ *
+ * Build with `addNode`, `addEdge` / `addConditionalEdge`, `setEntry`, and
+ * `setEnd`; the builder methods return `this` so they chain. `run` executes the
+ * graph from the entry node.
+ */
+export class Workflow {
+    maxSteps;
+    nodes = new Map();
+    edges = new Map();
+    entry;
+    constructor(maxSteps = 100) {
+        this.maxSteps = maxSteps;
+    }
+    /** Register a node `func` under `name` (used to reference it in edges). */
+    addNode(name, func) {
+        this.nodes.set(name, func);
+        return this;
+    }
+    /** Add a static edge `from` → `to`. */
+    addEdge(from, to) {
+        this.edges.set(from, { kind: 'node', to });
+        return this;
+    }
+    /**
+     * Add a conditional edge whose `router` picks the next node at runtime. The
+     * router returns the target node name, or `END` to terminate the workflow.
+     */
+    addConditionalEdge(from, router) {
+        this.edges.set(from, { kind: 'conditional', router });
+        return this;
+    }
+    /** Set the entry node (first node to execute). */
+    setEntry(name) {
+        this.entry = name;
+        return this;
+    }
+    /** Mark `from` as terminal — reaching it ends the workflow. */
+    setEnd(from) {
+        this.edges.set(from, { kind: 'end' });
+        return this;
+    }
+    /**
+     * Execute the workflow from the entry node, returning the final state.
+     *
+     * Throws {@link WorkflowError} if no entry node was set, a referenced node
+     * does not exist, or the `maxSteps` cap is exceeded (e.g. an unbroken cycle).
+     */
+    async run(initialState) {
+        if (this.entry === undefined) {
+            throw new WorkflowError('workflow has no entry node — call setEntry()');
+        }
+        if (!this.nodes.has(this.entry)) {
+            throw new WorkflowError(`entry node '${this.entry}' not found in registered nodes`);
+        }
+        let state = initialState;
+        let current = this.entry;
+        for (let step = 0; step < this.maxSteps; step++) {
+            const node = this.nodes.get(current);
+            if (node === undefined) {
+                throw new WorkflowError(`node '${current}' not found in workflow`);
+            }
+            state = await node(state);
+            const edge = this.edges.get(current);
+            if (edge === undefined || edge.kind === 'end') {
+                // No outgoing edge, or an explicit END — terminate.
+                return state;
+            }
+            if (edge.kind === 'conditional') {
+                const target = edge.router(state);
+                if (target === END)
+                    return state;
+                current = target;
+            }
+            else {
+                current = edge.to;
+            }
+        }
+        throw new WorkflowError(`workflow exceeded maxSteps (${this.maxSteps}) — possible infinite loop`);
+    }
+}
+//# sourceMappingURL=workflow.js.map

package/dist/workflow.js.map

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

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@smooai/smooth-operator-core",
+  "version": "0.1.0",
+  "description": "Native TypeScript implementation of the smooth-operator agent engine — an in-process, OpenAI-compatible agentic tool-calling loop with knowledge grounding. The TypeScript sibling of the Rust reference engine, the C# core, and the Python core.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SmooAI/smooth-operator-core.git",
+    "directory": "typescript/core"
+  },
+  "homepage": "https://github.com/SmooAI/smooth-operator-core/tree/main/typescript/core",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "openai": "^4.77.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}