bare-agent 0.16.2 → 0.18.0

package/src/remember.js

@@ -0,0 +1,163 @@
+'use strict';
+
+/**
+ * remember — the consolidation pass (eval-assist F5). The "future glue" the PRD parked: it turns the spans
+ * `stash` harvested out of the live transcript into durable facts, written back through the GENERIC four-verb
+ * `Store` socket (`store`/`search`/`get`/`delete`). Backend-agnostic by construction — works with the
+ * JsonFileStore, SQLite, litectx, or a custom store — so it carries NO litectx coupling (the reason the
+ * read-litectx's-promotion-count alternative was rejected: it reaches past the socket into one backend).
+ *
+ * One cheap LLM pass per span distills durable signal (decisions, config, identifiers, stable preferences)
+ * and DROPS ephemeral chatter, superseded values, and unanswered questions. The distiller prompt below is the
+ * one validated live on the real Anthropic wire in `poc/f5-remember-distill.mjs` (faithfulness + correction +
+ * discrimination, all falsifiable). A wrong distiller poisons Memory silently, so that POC must stay green.
+ *
+ * SECURITY — memory-poisoning surface: facts are model output distilled over UNTRUSTED transcript content and
+ * written to durable memory. The grounding prompt refuses a direct "record this fact" injection (validated in the
+ * F5 POC + integration test), but treat recalled facts as untrusted CONTEXT, never as authority — and never feed
+ * a recalled fact into a privileged action without the same gate you'd apply to any model output.
+ *
+ * Composes AROUND a Loop (like Evaluator/refine), never inside `loop.js`. Optional, flagged-and-deletable.
+ * Budget visibility: each distill pass forwards `usage` to `opts.onLlmResult` (mirror of Evaluator) so a wired
+ * bareguard gate keeps counting. A `HaltError` from the provider propagates clean. Metering: each fact write
+ * counts against `result.metrics.memory.facts` via the loop-lent `ctx.recordMemoryOp('facts')` hook — the
+ * honest producer that field waited for. `facts` is DISJOINT from `stored`: remember writes via `store.store`
+ * WITHOUT threading ctx, so it never also trips the generic-write counter.
+ */
+
+/** @typedef {import('../types').Provider} Provider */
+/** @typedef {import('../types').Store} Store */
+
+// The distiller prompt under test in poc/f5-remember-distill.mjs — proven faithful on the live wire.
+// This IS the artifact; do not edit without re-running that POC (it must stay able to FAIL).
+const DISTILL_PROMPT = [
+  'You distill durable, reusable memory from a finished work transcript.',
+  'Output ONLY a JSON array of short fact strings. No prose, no code fences.',
+  'A durable fact is one a future session would want: decisions, architecture, config values, stable preferences, identifiers.',
+  'Rules:',
+  '- Ground every fact in the transcript. NEVER infer or invent a value that is not stated.',
+  '- If a value was later corrected, record ONLY the final corrected value — drop the superseded one entirely.',
+  '- Ignore greetings, acknowledgements, transient status ("checking", "one sec"), and questions that went unanswered.',
+  '- If nothing durable is present, return exactly [].',
+].join('\n');
+
+/**
+ * @typedef {object} RememberOptions
+ * @property {Provider} provider - LLM provider implementing `generate(messages, tools, opts)`.
+ * @property {Pick<Store, 'store'>} store - The Store socket (or a `Memory` wrapper). remember writes through
+ *   `.store(content, metadata)` ONLY — no other verb, no backend assumptions.
+ * @property {string} [contract] - Optional definition of what counts as durable for this task; appended to the
+ *   distiller prompt to steer it (the A3 contract idea, reused on the write side).
+ * @property {Record<string, any>} [metadata] - Merged into every stored fact's metadata. `kind` is always `'fact'`
+ *   (NOT overridable — `remember` writes facts; `fact` is litectx's canonical durable kind and harmless to other
+ *   stores, so the stored label always matches the `facts` counter). Add ANY OTHER metadata here (tags, or litectx
+ *   `format`/`scope` to differentiate facts). NEVER carries ctx — ctx rides in its own option, never persisted.
+ * @property {{ recordMemoryOp?: (kind: string) => void } & Record<string, any>} [ctx] - The run ctx. If it carries
+ *   the loop-lent `recordMemoryOp`, each fact write counts against `result.metrics.memory.facts`.
+ * @property {(payload: { usage: any, model: string|null, kind: 'remember' }) => any} [onLlmResult] - Budget hook;
+ *   each distill pass forwards usage so a bareguard gate keeps counting (mirror of Evaluator).
+ * @property {string} [prompt] - Override the distiller system prompt (defaults to the F5-validated one).
+ */
+
+/**
+ * @typedef {object} RememberOutcome
+ * @property {string[]} facts - The facts written, in order — deduplicated within this call by exact string
+ *   (so `facts.length` is the count stored). Cross-run / semantic dedup is the store's/consumer's job.
+ * @property {number} spans - How many non-empty spans were processed.
+ */
+
+/**
+ * Distill durable facts from harvested spans and persist them through the Store socket.
+ *
+ * @param {Array<string | { content?: string, text?: string }>} spans - The harvested spans (stash's feedstock).
+ *   Each is a transcript chunk — a raw string, or an object with `content`/`text`. Empty/blank spans are skipped.
+ * @param {RememberOptions} options
+ * @returns {Promise<RememberOutcome>}
+ */
+async function remember(spans, options = /** @type {RememberOptions} */ ({})) {
+  if (!Array.isArray(spans)) throw new Error('[remember] spans must be an array');
+  const { provider, store } = options;
+  if (!provider || typeof provider.generate !== 'function') throw new Error('[remember] requires options.provider with a generate() method');
+  if (!store || typeof store.store !== 'function') throw new Error('[remember] requires options.store with a store() method');
+
+  const contract = typeof options.contract === 'string' && options.contract.trim() ? options.contract.trim() : null;
+  const baseMeta = options.metadata && typeof options.metadata === 'object' ? options.metadata : {};
+  const ctx = options.ctx;
+  /** @type {((kind: string) => void) | null} */
+  const recordFact = ctx && typeof ctx.recordMemoryOp === 'function' ? ctx.recordMemoryOp : null;
+  const onLlmResult = typeof options.onLlmResult === 'function' ? options.onLlmResult : null;
+  const sys = typeof options.prompt === 'string' && options.prompt.trim()
+    ? options.prompt
+    : (contract ? `${DISTILL_PROMPT}\n\nFor this task, "durable" specifically means:\n${contract}` : DISTILL_PROMPT);
+
+  /** @type {string[]} */
+  const all = [];
+  const seen = new Set(); // in-call exact-string dedup; cross-run / semantic dedup is the store's/consumer's job
+  let spanCount = 0;
+
+  for (const span of spans) {
+    const text = spanText(span);
+    if (!text) continue; // skip empty/blank — nothing to distill, and a blank prompt wastes a round
+    spanCount++;
+
+    const out = await provider.generate(
+      [{ role: 'system', content: sys }, { role: 'user', content: text }],
+      [],
+      { temperature: 0 },
+    );
+    if (onLlmResult) {
+      await onLlmResult({ usage: (out && out.usage) || null, model: (out && out.model) || provider.model || null, kind: 'remember' });
+    }
+
+    for (const fact of parseFacts(out && out.text)) {
+      if (seen.has(fact)) continue; // already written this call — don't double-store or double-count
+      seen.add(fact);
+      // Write via the generic socket WITHOUT ctx → counts as `facts`, not the generic `stored`.
+      // `kind:'fact'` is authoritative (AFTER the spread) so the stored label always matches the counter.
+      await store.store(fact, { ...baseMeta, kind: 'fact' });
+      if (recordFact) recordFact('facts');
+      all.push(fact);
+    }
+  }
+
+  return { facts: all, spans: spanCount };
+}
+
+/**
+ * Normalize a span to its text, or '' if there's nothing to distill.
+ * @param {any} span
+ * @returns {string}
+ */
+function spanText(span) {
+  let s = '';
+  if (typeof span === 'string') s = span;
+  else if (span && typeof span === 'object') s = typeof span.content === 'string' ? span.content : (typeof span.text === 'string' ? span.text : '');
+  return s.trim() ? s : '';
+}
+
+/**
+ * Lenient extraction of a JSON array of fact strings from raw model output (mirrors planner's parse).
+ * A model that returns prose / no array yields [] — NOT an error (the "nothing durable" case). A provider
+ * or network error is a different thing and propagates from generate(), never swallowed here.
+ * @param {any} text
+ * @returns {string[]}
+ */
+function parseFacts(text) {
+  if (typeof text !== 'string') return [];
+  const cleaned = text.replace(/^```(?:json)?\s*\n?/m, '').replace(/\n?```\s*$/m, '').trim();
+  let arr;
+  try {
+    arr = JSON.parse(cleaned);
+  } catch {
+    const match = cleaned.match(/\[[\s\S]*\]/);
+    if (!match) return [];
+    try { arr = JSON.parse(match[0]); } catch { return []; }
+  }
+  if (!Array.isArray(arr)) return [];
+  return arr
+    .map((f) => (typeof f === 'string' ? f : (f && typeof f === 'object' && typeof f.fact === 'string' ? f.fact : '')))
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+module.exports = { remember, DISTILL_PROMPT };

package/src/skills.d.ts

@@ -0,0 +1,71 @@
+export type ToolDef = import("../types").ToolDef;
+export type Skill = {
+    /**
+     * - Unique skill name (also the tool-name prefix).
+     */
+    name: string;
+    /**
+     * - One-line catalog entry shown in `skill_use`'s description.
+     */
+    description: string;
+    /**
+     * - Returned as the `skill_use` tool result when the skill is activated.
+     */
+    instructions: string;
+    /**
+     * - Tools unlocked on use; their names are auto-prefixed `${name}_${tool}`.
+     */
+    tools?: import("../types").ToolDef[] | undefined;
+};
+export class SkillRegistry {
+    /**
+     * @param {Object} [options]
+     * @param {Iterable<string>} [options.reserved] - Tool names already in use (native/MCP), so a prefixed
+     *   skill tool that would collide with one is rejected at `register` time. Tool names are globally unique
+     *   for DISPATCH (PRD §2.6, D6) — this is the collision check across native + MCP + skills, not security.
+     * @param {string} [options.metaToolName='skill_use'] - Override the meta-tool name if `skill_use` is taken.
+     */
+    constructor(options?: {
+        reserved?: Iterable<string> | undefined;
+        metaToolName?: string | undefined;
+    });
+    /** @type {Map<string, {name: string, description: string, instructions: string, tools: ToolDef[]}>} */
+    _skills: Map<string, {
+        name: string;
+        description: string;
+        instructions: string;
+        tools: ToolDef[];
+    }>;
+    /** @type {Set<string>} skill names the agent has activated this run */
+    _unlocked: Set<string>;
+    /** @type {Set<string>} every tool name owned by the registry (meta + all prefixed skill tools) */
+    _toolNames: Set<string>;
+    /** @type {Set<string>} externally-reserved names (native/MCP) for collision detection */
+    _reserved: Set<string>;
+    metaToolName: string;
+    /**
+     * The current active tool set: `[metaTool, ...tools of every unlocked skill]`. Pass this method (bound)
+     * as the Loop `tools` thunk — it is re-evaluated each round, so tools unlocked this round are offered next.
+     * @returns {ToolDef[]}
+     */
+    activeTools(): ToolDef[];
+    /**
+     * Register a skill. Throws on a duplicate skill name, or if a prefixed tool name collides with an
+     * existing native/MCP/skill tool (or the meta-tool). Returns `this` for chaining.
+     * @param {Skill} skill
+     * @returns {SkillRegistry}
+     */
+    register(skill: Skill): SkillRegistry;
+    /** Build the catalog block (one line per registered skill) for the meta-tool description. */
+    _catalog(): string;
+    /**
+     * The `skill_use` meta-tool ToolDef, with the current catalog in its description. Always included by
+     * `activeTools()`. Activating a skill injects its instructions (the tool result) and unlocks its tools.
+     * @returns {ToolDef}
+     */
+    get metaTool(): ToolDef;
+    /** Names of skills activated so far this run. @returns {string[]} */
+    unlocked(): string[];
+    /** Reset the unlocked set (e.g. between runs). The registered skills are kept. */
+    reset(): void;
+}

package/src/skills.js

@@ -0,0 +1,200 @@
+'use strict';
+
+// SkillRegistry — the eval-assist F2 skill mechanism (PRD §2.3–2.7).
+//
+// A skill is an operator-registered bundle `{ name, description, instructions, tools }` surfaced to the
+// agent by PROGRESSIVE DISCLOSURE: a single meta-tool `skill_use` carries a catalog of one-liners in its
+// description; until a skill is used, only its one-liner is in context — never its instructions or tool
+// schemas. On `skill_use({ name })`, two effects: (1) the skill's `instructions` are returned AS the tool
+// result (on-demand injection, lands naturally in the transcript), and (2) the skill's tools are unlocked
+// into the active tool set for subsequent rounds, called NATIVELY by their prefixed names.
+//
+// The genuine gap vs. MCP (which already does tools-on-demand): instructions injected per-invocation inside
+// the same agent's context budget — the context-engineering lever (PRD §2.2).
+//
+// Governance is unchanged (PRD §2.6, D5): the gate judges `(tool, args)` and ignores origin. Skills affect
+// DISCOVERY, never AUTHORIZATION — unlocking a tool authorizes nothing; bareguard decides each call blind to
+// how the tool was reached. `skill_use` itself, and every unlocked tool, flow through the SAME
+// `Loop({ policy })` chokepoint.
+//
+// The only Loop coupling is the general tools-as-thunk primitive (D4, src/loop.js): pass `activeTools` as
+// the `tools` thunk and the freshly-unlocked set is offered on the next round. Loop never imports this file.
+//
+// Separator is `_`, not `.` (POC-corrected, PRD §2.6): a dot is rejected by both OpenAI's
+// `^[a-zA-Z0-9_-]+$` and Anthropic's tool-name validators. Underscore is what MCP already uses
+// (`${server}_${tool}`); skills inherit it. Validated by poc/f2-skill-thunk.mjs on OpenAI + Anthropic.
+
+const { ValidationError, ToolError } = require('./errors');
+
+/** @typedef {import('../types').ToolDef} ToolDef */
+
+/**
+ * @typedef {Object} Skill
+ * @property {string} name - Unique skill name (also the tool-name prefix).
+ * @property {string} description - One-line catalog entry shown in `skill_use`'s description.
+ * @property {string} instructions - Returned as the `skill_use` tool result when the skill is activated.
+ * @property {ToolDef[]} [tools] - Tools unlocked on use; their names are auto-prefixed `${name}_${tool}`.
+ */
+
+const META_NAME = 'skill_use';
+
+// Provider-safe identifier charset. OpenAI enforces `^[a-zA-Z0-9_-]+$` on tool names and Anthropic the
+// same shape (the POC, poc/f2-skill-thunk.mjs, proved a dot is rejected at generate time). Skill names and
+// bare tool names must satisfy this so the prefixed result — joined by `_`, itself in the set — is accepted
+// by every provider. Validating at register() fails fast, instead of surfacing as a mid-run provider error.
+const SAFE_NAME = /^[a-zA-Z0-9_-]+$/;
+
+class SkillRegistry {
+  /**
+   * @param {Object} [options]
+   * @param {Iterable<string>} [options.reserved] - Tool names already in use (native/MCP), so a prefixed
+   *   skill tool that would collide with one is rejected at `register` time. Tool names are globally unique
+   *   for DISPATCH (PRD §2.6, D6) — this is the collision check across native + MCP + skills, not security.
+   * @param {string} [options.metaToolName='skill_use'] - Override the meta-tool name if `skill_use` is taken.
+   */
+  constructor(options = {}) {
+    /** @type {Map<string, {name: string, description: string, instructions: string, tools: ToolDef[]}>} */
+    this._skills = new Map();
+    /** @type {Set<string>} skill names the agent has activated this run */
+    this._unlocked = new Set();
+    /** @type {Set<string>} every tool name owned by the registry (meta + all prefixed skill tools) */
+    this._toolNames = new Set();
+    /** @type {Set<string>} externally-reserved names (native/MCP) for collision detection */
+    this._reserved = new Set(options.reserved || []);
+    this.metaToolName = options.metaToolName || META_NAME;
+    if (!SAFE_NAME.test(this.metaToolName)) {
+      throw new ValidationError(`[SkillRegistry] meta-tool name "${this.metaToolName}" must match ${SAFE_NAME} (provider tool-name charset).`);
+    }
+    if (this._reserved.has(this.metaToolName)) {
+      throw new ValidationError(`[SkillRegistry] meta-tool name "${this.metaToolName}" collides with a reserved tool name.`);
+    }
+    this._toolNames.add(this.metaToolName);
+    // Bind so callers can pass `skills.activeTools` directly as the Loop `tools` thunk (PRD §2.7) without
+    // losing `this`.
+    this.activeTools = this.activeTools.bind(this);
+  }
+
+  /**
+   * Register a skill. Throws on a duplicate skill name, or if a prefixed tool name collides with an
+   * existing native/MCP/skill tool (or the meta-tool). Returns `this` for chaining.
+   * @param {Skill} skill
+   * @returns {SkillRegistry}
+   */
+  register(skill) {
+    if (!skill || typeof skill !== 'object') {
+      throw new ValidationError('[SkillRegistry] register(skill) requires a { name, description, instructions, tools } object.');
+    }
+    const { name, description, instructions, tools = [] } = skill;
+    if (typeof name !== 'string' || !name) {
+      throw new ValidationError(`[SkillRegistry] skill name must be a non-empty string (got ${JSON.stringify(name)}).`);
+    }
+    if (!SAFE_NAME.test(name)) {
+      throw new ValidationError(`[SkillRegistry] skill name "${name}" must match ${SAFE_NAME} — it prefixes tool names, which providers reject outside that charset (e.g. a dot breaks OpenAI/Anthropic).`);
+    }
+    if (this._skills.has(name)) {
+      throw new ValidationError(`[SkillRegistry] duplicate skill name "${name}".`);
+    }
+    if (typeof description !== 'string' || !description) {
+      throw new ValidationError(`[SkillRegistry] skill "${name}" needs a non-empty string description (the catalog line).`);
+    }
+    if (typeof instructions !== 'string' || !instructions) {
+      throw new ValidationError(`[SkillRegistry] skill "${name}" needs non-empty string instructions (injected on use).`);
+    }
+    if (!Array.isArray(tools)) {
+      throw new ValidationError(`[SkillRegistry] skill "${name}" tools must be an array (got ${typeof tools}).`);
+    }
+
+    // Prefix each tool name for global dispatch uniqueness, validating collisions BEFORE committing any
+    // (a half-registered skill would be worse than a clean throw).
+    /** @type {ToolDef[]} */
+    const prefixed = [];
+    const seenThisSkill = new Set();
+    for (const tool of tools) {
+      if (!tool || typeof tool.name !== 'string' || !tool.name) {
+        throw new ValidationError(`[SkillRegistry] skill "${name}" has a tool with no name.`);
+      }
+      if (typeof tool.execute !== 'function') {
+        throw new ValidationError(`[SkillRegistry] skill "${name}" tool "${tool.name}" is missing an execute() function.`);
+      }
+      if (!SAFE_NAME.test(tool.name)) {
+        throw new ValidationError(`[SkillRegistry] skill "${name}" tool name "${tool.name}" must match ${SAFE_NAME} (provider tool-name charset).`);
+      }
+      const fullName = `${name}_${tool.name}`;
+      if (seenThisSkill.has(fullName)) {
+        throw new ValidationError(`[SkillRegistry] skill "${name}" defines "${tool.name}" twice.`);
+      }
+      if (this._toolNames.has(fullName) || this._reserved.has(fullName)) {
+        throw new ValidationError(`[SkillRegistry] skill "${name}" tool "${fullName}" collides with an existing native/MCP/skill tool name.`);
+      }
+      seenThisSkill.add(fullName);
+      prefixed.push({ ...tool, name: fullName });
+    }
+
+    for (const t of prefixed) this._toolNames.add(t.name);
+    this._skills.set(name, { name, description, instructions, tools: prefixed });
+    return this;
+  }
+
+  /** Build the catalog block (one line per registered skill) for the meta-tool description. */
+  _catalog() {
+    if (this._skills.size === 0) return '(no skills registered)';
+    return [...this._skills.values()].map(s => `  ${s.name}: ${s.description}`).join('\n');
+  }
+
+  /**
+   * The `skill_use` meta-tool ToolDef, with the current catalog in its description. Always included by
+   * `activeTools()`. Activating a skill injects its instructions (the tool result) and unlocks its tools.
+   * @returns {ToolDef}
+   */
+  get metaTool() {
+    const registry = this;
+    return {
+      name: this.metaToolName,
+      description:
+        'Reveal and activate a registered skill by name. Returns the skill\'s instructions and unlocks its '
+        + 'tools (callable by their namespaced names on subsequent turns). Available skills:\n'
+        + this._catalog(),
+      parameters: {
+        type: 'object',
+        properties: { name: { type: 'string', description: 'The name of the skill to activate.' } },
+        required: ['name'],
+      },
+      execute: async ({ name } = {}) => {
+        const skill = registry._skills.get(name);
+        if (!skill) {
+          const known = [...registry._skills.keys()].join(', ') || '(none)';
+          throw new ToolError(`[skill_use] unknown skill "${name}". Registered skills: ${known}.`);
+        }
+        registry._unlocked.add(name);
+        return skill.instructions;
+      },
+    };
+  }
+
+  /**
+   * The current active tool set: `[metaTool, ...tools of every unlocked skill]`. Pass this method (bound)
+   * as the Loop `tools` thunk — it is re-evaluated each round, so tools unlocked this round are offered next.
+   * @returns {ToolDef[]}
+   */
+  activeTools() {
+    /** @type {ToolDef[]} */
+    const out = [this.metaTool];
+    for (const name of this._unlocked) {
+      const skill = this._skills.get(name);
+      if (skill) out.push(...skill.tools);
+    }
+    return out;
+  }
+
+  /** Names of skills activated so far this run. @returns {string[]} */
+  unlocked() {
+    return [...this._unlocked];
+  }
+
+  /** Reset the unlocked set (e.g. between runs). The registered skills are kept. */
+  reset() {
+    this._unlocked.clear();
+  }
+}
+
+module.exports = { SkillRegistry };

package/src/stash.d.ts

@@ -0,0 +1,44 @@
+export type ToolDef = import("../types").ToolDef;
+/**
+ * Build the stash reference skill + the trim function that executes its folds.
+ *
+ * @param {Object} [options]
+ * @param {'summarize'|'stash'} [options.defaultStrategy='summarize'] - Strategy when the model omits one.
+ *   'summarize' (OQ5 lean / §2.11) is lossy; 'stash' is lossless. 'summarize' degrades to a lossless park
+ *   when no `ctx.summarize` is wired (loud, never a silent detail-loss).
+ * @param {string} [options.keyPrefix='stash:'] - Namespace for stash/episode ids.
+ * @param {number} [options.maxLabels=128] - LRU backstop on DISTINCT live labels (§2.13) — visible, not silent.
+ * @param {Object} [options.compaction] - AUTOMATIC token-pressure trigger (§2.11/D12, all bareagent — a
+ *   housekeeping threshold, NEVER a bareguard halt bound). Opt-in: omit, or omit `ceilingTokens`, → OFF
+ *   (no guessed model→window table). Fires on the NEXT round's trim when the Loop's measured
+ *   `ctx.usage.inputTokens / ceilingTokens > triggerAt`.
+ * @param {number} [options.compaction.ceilingTokens] - OPERATOR-SET context ceiling (enables auto-trigger).
+ * @param {number} [options.compaction.triggerAt=0.7] - Fraction of the ceiling that fires a fold.
+ * @param {'summarize'|'stash'} [options.compaction.strategy] - Strategy for auto-folds (default: defaultStrategy).
+ * @param {number} [options.compaction.keepHeadTurns=1] - Recent turns to keep at the START (initial context).
+ * @param {number} [options.compaction.keepRecentTurns=3] - Recent turns to keep at the END (live working set).
+ * @param {(msg: string) => void} [options.onNote=console.warn] - Sink for the loud one-time/backstop notes.
+ * @returns {{ skill: { name: string, description: string, instructions: string, tools: ToolDef[] }, trim: (msgs: any[], ctx: any) => Promise<any[]>, restoreHandles: () => string[] }}
+ */
+export function createStashSkill(options?: {
+    defaultStrategy?: "summarize" | "stash" | undefined;
+    keyPrefix?: string | undefined;
+    maxLabels?: number | undefined;
+    compaction?: {
+        ceilingTokens?: number | undefined;
+        triggerAt?: number | undefined;
+        strategy?: "summarize" | "stash" | undefined;
+        keepHeadTurns?: number | undefined;
+        keepRecentTurns?: number | undefined;
+    } | undefined;
+    onNote?: ((msg: string) => void) | undefined;
+}): {
+    skill: {
+        name: string;
+        description: string;
+        instructions: string;
+        tools: ToolDef[];
+    };
+    trim: (msgs: any[], ctx: any) => Promise<any[]>;
+    restoreHandles: () => string[];
+};