@agnt5/sdk 0.2.1

package/dist/scorer.js

@@ -0,0 +1,211 @@
+/**
+ * Scorer framework for evaluating component outputs.
+ *
+ * Provides a @scorer decorator, registry, built-in scorers, and
+ * a ScorerRequest/ScorerResult protocol matching the Python SDK.
+ */
+import { randomUUID } from 'crypto';
+/** Result of a scorer evaluation */
+export class ScorerResult {
+    constructor(opts) {
+        this.score = Math.max(0, Math.min(1, opts.score));
+        this.passed = opts.passed ?? this.score >= 0.5;
+        this.label = opts.label;
+        this.explanation = opts.explanation;
+        this.metadata = opts.metadata;
+    }
+    /** Create a passing result */
+    static pass(explanation) {
+        return new ScorerResult({ score: 1.0, passed: true, explanation });
+    }
+    /** Create a failing result */
+    static fail(explanation) {
+        return new ScorerResult({ score: 0.0, passed: false, explanation });
+    }
+}
+// ─── Scorer decorator ────────────────────────────────────────────────
+const SCORER_MARKER = Symbol('scorer');
+/**
+ * Decorator to register a function as a scorer.
+ *
+ * @example
+ * ```typescript
+ * const checkFormat = scorer('format_check', 'Checks output format')(
+ *   async (ctx, request) => {
+ *     const valid = typeof request.output === 'string';
+ *     return new ScorerResult({ score: valid ? 1 : 0, passed: valid });
+ *   }
+ * );
+ * ```
+ */
+export function scorer(name, description) {
+    return function (handler) {
+        const scorerName = name || handler.name || 'unnamed_scorer';
+        const config = {
+            name: scorerName,
+            handler,
+            description: description || '',
+            isAsync: handler.constructor.name === 'AsyncFunction',
+        };
+        handler[SCORER_MARKER] = config;
+        ScorerRegistry.register(config);
+        return handler;
+    };
+}
+/** Check if a function is a scorer */
+export function isScorer(fn) {
+    return fn && fn[SCORER_MARKER] !== undefined;
+}
+/** Get scorer config from a decorated function */
+export function getScorerConfig(fn) {
+    return fn?.[SCORER_MARKER];
+}
+// ─── Registry ────────────────────────────────────────────────────────
+/**
+ * Global registry for scorer components.
+ */
+export class ScorerRegistry {
+    static register(config) {
+        this._scorers.set(config.name, config);
+    }
+    static get(name) {
+        return this._scorers.get(name);
+    }
+    static all() {
+        return new Map(this._scorers);
+    }
+    static listNames() {
+        return Array.from(this._scorers.keys());
+    }
+    static clear() {
+        this._scorers.clear();
+    }
+}
+ScorerRegistry._scorers = new Map();
+// ─── Built-in scorers ────────────────────────────────────────────────
+/** Exact match: output === expected */
+export function exactMatch(request) {
+    const output = String(request.output ?? '');
+    const expected = String(request.expected ?? '');
+    const match = output === expected;
+    return new ScorerResult({
+        score: match ? 1.0 : 0.0,
+        passed: match,
+        explanation: match ? 'Exact match' : `Expected "${expected}", got "${output}"`,
+    });
+}
+/** Contains: output includes expected substring */
+export function contains(request) {
+    const output = String(request.output ?? '');
+    const expected = String(request.expected ?? '');
+    const found = output.includes(expected);
+    return new ScorerResult({
+        score: found ? 1.0 : 0.0,
+        passed: found,
+        explanation: found ? `Output contains "${expected}"` : `Output does not contain "${expected}"`,
+    });
+}
+/** JSON valid: output is valid JSON */
+export function jsonValid(request) {
+    const output = String(request.output ?? '');
+    try {
+        JSON.parse(output);
+        return new ScorerResult({ score: 1.0, passed: true, explanation: 'Valid JSON' });
+    }
+    catch {
+        return new ScorerResult({ score: 0.0, passed: false, explanation: 'Invalid JSON' });
+    }
+}
+/** Regex match: output matches the expected regex pattern */
+export function regexMatch(request) {
+    const output = String(request.output ?? '');
+    const pattern = String(request.expected ?? '');
+    try {
+        const re = new RegExp(pattern);
+        const match = re.test(output);
+        return new ScorerResult({
+            score: match ? 1.0 : 0.0,
+            passed: match,
+            explanation: match ? `Matches /${pattern}/` : `Does not match /${pattern}/`,
+        });
+    }
+    catch {
+        return new ScorerResult({
+            score: 0.0,
+            passed: false,
+            explanation: `Invalid regex pattern: ${pattern}`,
+        });
+    }
+}
+/** Levenshtein distance: normalized similarity score */
+export function levenshtein(request) {
+    const output = String(request.output ?? '');
+    const expected = String(request.expected ?? '');
+    if (output === expected) {
+        return new ScorerResult({ score: 1.0, passed: true, explanation: 'Exact match' });
+    }
+    const maxLen = Math.max(output.length, expected.length);
+    if (maxLen === 0) {
+        return new ScorerResult({ score: 1.0, passed: true, explanation: 'Both empty' });
+    }
+    // Compute edit distance
+    const m = output.length;
+    const n = expected.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = output[i - 1] === expected[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+        }
+    }
+    const distance = dp[m][n];
+    const score = 1 - distance / maxLen;
+    return new ScorerResult({
+        score,
+        passed: score >= 0.5,
+        explanation: `Edit distance: ${distance}, similarity: ${(score * 100).toFixed(1)}%`,
+    });
+}
+// Register built-in scorers
+ScorerRegistry.register({ name: 'exact_match', handler: (_ctx, req) => exactMatch(req), description: 'Exact string match', isAsync: false });
+ScorerRegistry.register({ name: 'contains', handler: (_ctx, req) => contains(req), description: 'Substring containment check', isAsync: false });
+ScorerRegistry.register({ name: 'json_valid', handler: (_ctx, req) => jsonValid(req), description: 'Valid JSON check', isAsync: false });
+ScorerRegistry.register({ name: 'regex_match', handler: (_ctx, req) => regexMatch(req), description: 'Regex pattern match', isAsync: false });
+ScorerRegistry.register({ name: 'levenshtein', handler: (_ctx, req) => levenshtein(req), description: 'Levenshtein edit distance', isAsync: false });
+// ─── Runner ──────────────────────────────────────────────────────────
+/**
+ * Run a scorer by name against a request.
+ */
+export async function runScorer(scorerName, request, ctx) {
+    const config = ScorerRegistry.get(scorerName);
+    if (!config) {
+        throw new Error(`Scorer '${scorerName}' not found in registry`);
+    }
+    const scorerCtx = ctx || {
+        runId: randomUUID(),
+        correlationId: randomUUID(),
+        attempt: 0,
+        log: () => { },
+    };
+    return config.handler(scorerCtx, request);
+}
+// ─── Helpers ─────────────────────────────────────────────────────────
+/** Helper methods for ScorerRequest */
+export function getRequestConfig(request, key, defaultValue) {
+    return request.config?.[key] ?? defaultValue;
+}
+/** Get trace events by type from a ScorerRequest */
+export function getTraceEvents(request, eventType) {
+    return (request.trace || []).filter(e => e.eventType === eventType);
+}
+/** Get total tokens from trace events */
+export function getTotalTokens(request) {
+    return (request.trace || [])
+        .filter(e => e.eventType === 'lm.call.completed')
+        .reduce((sum, e) => sum + (e.data.total_tokens || 0), 0);
+}
+//# sourceMappingURL=scorer.js.map

package/dist/scorer.js.map

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

package/dist/state.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Scoped state management for AGNT5 components.
+ *
+ * Provides run/session/user scoped state with lazy loading
+ * and an in-memory backend (platform-backed adapter can be swapped in later).
+ */
+/**
+ * State adapter interface for pluggable backends.
+ * The in-memory adapter is used by default; a platform-backed adapter
+ * can be provided to persist state via the Rust core / gRPC.
+ */
+export interface StateAdapter {
+    load(scope: string, scopeId: string): Promise<Record<string, any> | null>;
+    save(scope: string, scopeId: string, state: Record<string, any>): Promise<void>;
+}
+/**
+ * In-memory state adapter (default).
+ * State lives only for the duration of the process.
+ */
+export declare class MemoryStateAdapter implements StateAdapter {
+    private store;
+    private key;
+    load(scope: string, scopeId: string): Promise<Record<string, any> | null>;
+    save(scope: string, scopeId: string, state: Record<string, any>): Promise<void>;
+}
+/**
+ * Scoped state manager with lazy loading.
+ *
+ * @example
+ * ```typescript
+ * const state = new StateManager(adapter, 'run', 'run-123');
+ * await state.set('phase', 'research');
+ * const phase = await state.get('phase'); // 'research'
+ * ```
+ */
+export declare class StateManager {
+    private _adapter;
+    private _scope;
+    private _scopeId;
+    private _cache;
+    private _loaded;
+    constructor(adapter: StateAdapter, scope: string, scopeId: string);
+    /** Lazy-load state on first access */
+    private ensureLoaded;
+    /** Save current state to adapter */
+    private save;
+    get<T = any>(key: string, defaultValue?: T): Promise<T | undefined>;
+    set<T = any>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    keys(): Promise<string[]>;
+    getAll(): Promise<Record<string, any>>;
+}
+/**
+ * Session-scoped context with its own StateManager.
+ */
+export declare class SessionContext {
+    readonly sessionId: string;
+    private _state;
+    constructor(adapter: StateAdapter, sessionId: string);
+    get state(): StateManager;
+}
+/**
+ * User-scoped context with its own StateManager.
+ */
+export declare class UserContext {
+    readonly userId: string;
+    private _state;
+    constructor(adapter: StateAdapter, userId: string);
+    get state(): StateManager;
+}
+/**
+ * Scoped state container providing run/session/user state access.
+ * Properties are lazily created on first access.
+ */
+export declare class ScopedState {
+    private _adapter;
+    private _runId;
+    private _sessionId;
+    private _userId;
+    private _runState?;
+    private _session?;
+    private _user?;
+    constructor(adapter: StateAdapter, runId: string, sessionId?: string | null, userId?: string | null);
+    /** Run-scoped state (ephemeral, cleared when run completes) */
+    get run(): StateManager;
+    /** Session-scoped context (multi-turn conversation state) */
+    get session(): SessionContext | null;
+    /** User-scoped context (long-term user preferences) */
+    get user(): UserContext | null;
+}
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

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

package/dist/state.js

@@ -0,0 +1,151 @@
+/**
+ * Scoped state management for AGNT5 components.
+ *
+ * Provides run/session/user scoped state with lazy loading
+ * and an in-memory backend (platform-backed adapter can be swapped in later).
+ */
+/**
+ * In-memory state adapter (default).
+ * State lives only for the duration of the process.
+ */
+export class MemoryStateAdapter {
+    constructor() {
+        this.store = new Map();
+    }
+    key(scope, scopeId) {
+        return `${scope}:${scopeId}`;
+    }
+    async load(scope, scopeId) {
+        return this.store.get(this.key(scope, scopeId)) ?? null;
+    }
+    async save(scope, scopeId, state) {
+        this.store.set(this.key(scope, scopeId), { ...state });
+    }
+}
+/**
+ * Scoped state manager with lazy loading.
+ *
+ * @example
+ * ```typescript
+ * const state = new StateManager(adapter, 'run', 'run-123');
+ * await state.set('phase', 'research');
+ * const phase = await state.get('phase'); // 'research'
+ * ```
+ */
+export class StateManager {
+    constructor(adapter, scope, scopeId) {
+        this._cache = null;
+        this._loaded = false;
+        this._adapter = adapter;
+        this._scope = scope;
+        this._scopeId = scopeId;
+    }
+    /** Lazy-load state on first access */
+    async ensureLoaded() {
+        if (this._loaded)
+            return;
+        const data = await this._adapter.load(this._scope, this._scopeId);
+        this._cache = data ?? {};
+        this._loaded = true;
+    }
+    /** Save current state to adapter */
+    async save() {
+        if (this._cache) {
+            await this._adapter.save(this._scope, this._scopeId, this._cache);
+        }
+    }
+    async get(key, defaultValue) {
+        await this.ensureLoaded();
+        const val = this._cache[key];
+        return val !== undefined ? val : defaultValue;
+    }
+    async set(key, value) {
+        await this.ensureLoaded();
+        this._cache[key] = value;
+        await this.save();
+    }
+    async delete(key) {
+        await this.ensureLoaded();
+        if (key in this._cache) {
+            delete this._cache[key];
+            await this.save();
+            return true;
+        }
+        return false;
+    }
+    async clear() {
+        this._cache = {};
+        this._loaded = true;
+        await this.save();
+    }
+    async keys() {
+        await this.ensureLoaded();
+        return Object.keys(this._cache);
+    }
+    async getAll() {
+        await this.ensureLoaded();
+        return { ...this._cache };
+    }
+}
+/**
+ * Session-scoped context with its own StateManager.
+ */
+export class SessionContext {
+    constructor(adapter, sessionId) {
+        this.sessionId = sessionId;
+        this._state = new StateManager(adapter, 'session', sessionId);
+    }
+    get state() {
+        return this._state;
+    }
+}
+/**
+ * User-scoped context with its own StateManager.
+ */
+export class UserContext {
+    constructor(adapter, userId) {
+        this.userId = userId;
+        this._state = new StateManager(adapter, 'user', userId);
+    }
+    get state() {
+        return this._state;
+    }
+}
+/**
+ * Scoped state container providing run/session/user state access.
+ * Properties are lazily created on first access.
+ */
+export class ScopedState {
+    constructor(adapter, runId, sessionId, userId) {
+        this._adapter = adapter;
+        this._runId = runId;
+        this._sessionId = sessionId ?? null;
+        this._userId = userId ?? null;
+    }
+    /** Run-scoped state (ephemeral, cleared when run completes) */
+    get run() {
+        if (!this._runState) {
+            this._runState = new StateManager(this._adapter, 'run', this._runId);
+        }
+        return this._runState;
+    }
+    /** Session-scoped context (multi-turn conversation state) */
+    get session() {
+        if (!this._sessionId)
+            return null;
+        if (!this._session) {
+            this._session = new SessionContext(this._adapter, this._sessionId);
+        }
+        return this._session;
+    }
+    /** User-scoped context (long-term user preferences) */
+    get user() {
+        if (!this._userId)
+            return null;
+        if (!this._user) {
+            this._user = new UserContext(this._adapter, this._userId);
+        }
+        return this._user;
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IAA/B;QACU,UAAK,GAAG,IAAI,GAAG,EAA+B,CAAC;IAazD,CAAC;IAXS,GAAG,CAAC,KAAa,EAAE,OAAe;QACxC,OAAO,GAAG,KAAK,IAAI,OAAO,EAAE,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAa,EAAE,OAAe;QACvC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAa,EAAE,OAAe,EAAE,KAA0B;QACnE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;IACzD,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,YAAY;IAOvB,YAAY,OAAqB,EAAE,KAAa,EAAE,OAAe;QAHzD,WAAM,GAA+B,IAAI,CAAC;QAC1C,YAAO,GAAG,KAAK,CAAC;QAGtB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,sCAAsC;IAC9B,KAAK,CAAC,YAAY;QACxB,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAClE,IAAI,CAAC,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;IAED,oCAAoC;IAC5B,KAAK,CAAC,IAAI;QAChB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAG,CAAU,GAAW,EAAE,YAAgB;QAC9C,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,IAAI,CAAC,MAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,GAAG,CAAU,GAAW,EAAE,KAAQ;QACtC,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;QAC1B,IAAI,CAAC,MAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QAC1B,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;QAC1B,IAAI,GAAG,IAAI,IAAI,CAAC,MAAO,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC,MAAO,CAAC,GAAG,CAAC,CAAC;YACzB,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;YAClB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;QAC1B,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAO,CAAC,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,MAAM;QACV,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;QAC1B,OAAO,EAAE,GAAG,IAAI,CAAC,MAAO,EAAE,CAAC;IAC7B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,cAAc;IAIzB,YAAY,OAAqB,EAAE,SAAiB;QAClD,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,WAAW;IAItB,YAAY,OAAqB,EAAE,MAAc;QAC/C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,WAAW;IAUtB,YACE,OAAqB,EACrB,KAAa,EACb,SAAyB,EACzB,MAAsB;QAEtB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,UAAU,GAAG,SAAS,IAAI,IAAI,CAAC;QACpC,IAAI,CAAC,OAAO,GAAG,MAAM,IAAI,IAAI,CAAC;IAChC,CAAC;IAED,+DAA+D;IAC/D,IAAI,GAAG;QACL,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,IAAI,CAAC,SAAS,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACvE,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,6DAA6D;IAC7D,IAAI,OAAO;QACT,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,OAAO,IAAI,CAAC;QAClC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,QAAQ,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACrE,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,uDAAuD;IACvD,IAAI,IAAI;QACN,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,KAAK,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5D,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;CACF"}

package/dist/tool.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Tool component for Agent capabilities.
+ *
+ * Tools wrap functions with structured interfaces for agent invocation.
+ * Phase 1: In-memory execution with basic schema support
+ * Phase 2: Platform integration with durable execution
+ */
+import type { Context, ToolHandler, ToolOptions, ToolSchema, JSONSchema } from './types.js';
+import type { ContextImpl } from './context.js';
+/**
+ * Tool class representing a callable tool for agents
+ */
+export declare class Tool<TInput = any, TOutput = any> {
+    readonly name: string;
+    readonly description: string;
+    readonly handler: ToolHandler<TInput, TOutput>;
+    readonly inputSchema: JSONSchema;
+    readonly confirmation: boolean;
+    readonly outputSchema?: JSONSchema;
+    constructor(name: string, description: string, handler: ToolHandler<TInput, TOutput>, options?: Partial<ToolOptions>);
+    /**
+     * Invoke the tool with given arguments
+     */
+    invoke(ctx: Context, args: Record<string, any>): Promise<TOutput>;
+    /**
+     * Get complete tool schema for agent consumption
+     */
+    getSchema(): ToolSchema;
+}
+/**
+ * Global registry for tools
+ */
+export declare class ToolRegistry {
+    private static tools;
+    /**
+     * Register a tool
+     */
+    static register(tool: Tool): void;
+    /**
+     * Get a tool by name
+     */
+    static get(name: string): Tool | undefined;
+    /**
+     * Get all registered tools
+     */
+    static all(): Map<string, Tool>;
+    /**
+     * List all tool names
+     */
+    static listNames(): string[];
+    /**
+     * Clear all registered tools (for testing)
+     */
+    static clear(): void;
+}
+/**
+ * Decorator to mark a function as a tool
+ *
+ * @example
+ * ```typescript
+ * const searchWeb = tool('search_web', {
+ *   description: 'Search the web for information',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: {
+ *       query: { type: 'string', description: 'Search query' },
+ *       maxResults: { type: 'integer', description: 'Max results' }
+ *     },
+ *     required: ['query']
+ *   }
+ * }, async (ctx, args) => {
+ *   const { query, maxResults = 10 } = args;
+ *   // Implementation
+ *   return results;
+ * });
+ * ```
+ */
+export declare function tool<TInput = any, TOutput = any>(name: string, options: ToolOptions, handler: ToolHandler<TInput, TOutput>): ToolHandler<TInput, TOutput>;
+/**
+ * Built-in tool that agents can use to request text input from users.
+ *
+ * Pauses workflow execution and waits for the user to provide a text response.
+ *
+ * @example
+ * ```typescript
+ * const agent = new Agent({
+ *   name: 'research_agent',
+ *   model: LM.openai(),
+ *   instructions: 'You are a research assistant.',
+ *   tools: [new AskUserTool(wfCtx)],
+ * });
+ * ```
+ */
+export declare class AskUserTool extends Tool<{
+    question: string;
+}, string | null> {
+    constructor(context: ContextImpl);
+}
+/**
+ * Built-in tool that agents can use to request approval from users.
+ *
+ * Pauses workflow execution and presents approve/reject options to the user.
+ *
+ * @example
+ * ```typescript
+ * const agent = new Agent({
+ *   name: 'deploy_agent',
+ *   model: LM.openai(),
+ *   instructions: 'You help deploy code changes safely.',
+ *   tools: [new RequestApprovalTool(wfCtx)],
+ * });
+ * ```
+ */
+export declare class RequestApprovalTool extends Tool<{
+    action: string;
+    details?: string;
+}, string | null> {
+    constructor(context: ContextImpl);
+}
+//# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC5F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD;;GAEG;AACH,qBAAa,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,UAAU,CAAC;gBAGjC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,OAAO,GAAE,OAAO,CAAC,WAAW,CAAM;IAepC;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBvE;;OAEG;IACH,SAAS,IAAI,UAAU;CAQxB;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAgC;IAEpD;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAOjC;;OAEG;IACH,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAI1C;;OAEG;IACH,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;IAI/B;;OAEG;IACH,MAAM,CAAC,SAAS,IAAI,MAAM,EAAE;IAI5B;;OAEG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;CAGrB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,EAC9C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAyB9B;AAID;;;;;;;;;;;;;;GAcG;AACH,qBAAa,WAAY,SAAQ,IAAI,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,GAAG,IAAI,CAAC;gBAC5D,OAAO,EAAE,WAAW;CA0BjC;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAoB,SAAQ,IAAI,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,GAAG,IAAI,CAAC;gBACpF,OAAO,EAAE,WAAW;CAqCjC"}