opensquid 0.5.395

package/dist/runtime/skill_prefilter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Embedder pre-filter for skill candidate selection (Phase 3 Task 3.3).
+ *
+ * Purpose: given a task subject string and a flat list of skills, rank
+ * skills by cosine similarity between the subject embedding and each
+ * skill's prose embedding, then return the top-K. The router (Task 3.4)
+ * consumes this shortlist — the LLM classifier sees ~10 skills instead
+ * of every skill in every pack, which keeps the prompt tractable and
+ * the per-task token cost bounded.
+ *
+ * Two-tier design (per `project_opensquid_reduced_context_first_principle`
+ * — "less in context = less drift"): the embedder is the cheap filter,
+ * the model-aliased classifier is the expensive sort. Top-K of cosine
+ * recall is sufficient because the classifier handles precision; we
+ * deliberately bias toward recall here.
+ *
+ * Failure mode is "fall through to load-everything" — if Ollama is
+ * unreachable, returning every skill is the correct behavior. The
+ * router then re-filters via `fast_classifier`, or, in the worst
+ * case (both unavailable), the runtime loads every skill, which is
+ * the same condition you'd be in WITHOUT this layer. That's the
+ * design ladder: each layer is an optional optimization, not a gate.
+ *
+ * Cache contract: callers supply a `Map<string, number[]>` keyed by
+ * the prose string used to embed. The cache is content-addressed —
+ * if a skill's prose changes, the new key won't hit, the new vector
+ * gets stored, and the stale entry harmlessly stays in the map until
+ * the caller decides to evict it. Phase 3 leaves invalidation to
+ * consumers per the risk callout.
+ *
+ * Imports from: ../rag/ollama_client.js (the shared Ollama embed
+ *   client used by the libsql RAG backend — single dependency point
+ *   on the embedder), ./types.js (Skill type).
+ * Imported by: src/runtime/index.ts (re-exported as `prefilterSkills`)
+ *   and the dispatcher pipeline once Phase 3 wiring lands.
+ */
+import type { Skill } from './types.js';
+export interface PrefilterOptions {
+    k?: number;
+    ollamaUrl?: string;
+    cache?: Map<string, number[]>;
+}
+/**
+ * Rank skills by embedding similarity to `taskSubject`; return top-K.
+ *
+ * Behavior:
+ *  - Empty `skills`        → `[]` (cheap short-circuit).
+ *  - Ollama unreachable on subject embedding → return ALL skills (fallback).
+ *  - Ollama unreachable on a skill's embedding → skip that skill (still
+ *    rank the rest). This is intentional asymmetry: a one-off skill
+ *    fetch failure shouldn't blow up the whole rank, but if the very
+ *    first call fails the embedder is presumed dead.
+ *  - `k > skills.length`   → all (post-rank) skills.
+ *
+ * Cosine is computed inline (no extra dep). The formula's denominator
+ * guards against zero-norm vectors by `|| 1` — that turns a degenerate
+ * "embedded the empty string" case into a 0 score rather than NaN.
+ */
+export declare function prefilterSkills(taskSubject: string, skills: Skill[], opts?: PrefilterOptions): Promise<Skill[]>;
+//# sourceMappingURL=skill_prefilter.d.ts.map

package/dist/runtime/skill_prefilter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill_prefilter.d.ts","sourceRoot":"","sources":["../../src/runtime/skill_prefilter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAaxC,MAAM,WAAW,gBAAgB;IAC/B,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,KAAK,EAAE,EACf,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,KAAK,EAAE,CAAC,CAuClB"}

package/dist/runtime/skill_prefilter.js

@@ -0,0 +1,117 @@
+/**
+ * Embedder pre-filter for skill candidate selection (Phase 3 Task 3.3).
+ *
+ * Purpose: given a task subject string and a flat list of skills, rank
+ * skills by cosine similarity between the subject embedding and each
+ * skill's prose embedding, then return the top-K. The router (Task 3.4)
+ * consumes this shortlist — the LLM classifier sees ~10 skills instead
+ * of every skill in every pack, which keeps the prompt tractable and
+ * the per-task token cost bounded.
+ *
+ * Two-tier design (per `project_opensquid_reduced_context_first_principle`
+ * — "less in context = less drift"): the embedder is the cheap filter,
+ * the model-aliased classifier is the expensive sort. Top-K of cosine
+ * recall is sufficient because the classifier handles precision; we
+ * deliberately bias toward recall here.
+ *
+ * Failure mode is "fall through to load-everything" — if Ollama is
+ * unreachable, returning every skill is the correct behavior. The
+ * router then re-filters via `fast_classifier`, or, in the worst
+ * case (both unavailable), the runtime loads every skill, which is
+ * the same condition you'd be in WITHOUT this layer. That's the
+ * design ladder: each layer is an optional optimization, not a gate.
+ *
+ * Cache contract: callers supply a `Map<string, number[]>` keyed by
+ * the prose string used to embed. The cache is content-addressed —
+ * if a skill's prose changes, the new key won't hit, the new vector
+ * gets stored, and the stale entry harmlessly stays in the map until
+ * the caller decides to evict it. Phase 3 leaves invalidation to
+ * consumers per the risk callout.
+ *
+ * Imports from: ../rag/ollama_client.js (the shared Ollama embed
+ *   client used by the libsql RAG backend — single dependency point
+ *   on the embedder), ./types.js (Skill type).
+ * Imported by: src/runtime/index.ts (re-exported as `prefilterSkills`)
+ *   and the dispatcher pipeline once Phase 3 wiring lands.
+ */
+import { ollamaEmbed } from '../rag/ollama_client.js';
+/**
+ * Rank skills by embedding similarity to `taskSubject`; return top-K.
+ *
+ * Behavior:
+ *  - Empty `skills`        → `[]` (cheap short-circuit).
+ *  - Ollama unreachable on subject embedding → return ALL skills (fallback).
+ *  - Ollama unreachable on a skill's embedding → skip that skill (still
+ *    rank the rest). This is intentional asymmetry: a one-off skill
+ *    fetch failure shouldn't blow up the whole rank, but if the very
+ *    first call fails the embedder is presumed dead.
+ *  - `k > skills.length`   → all (post-rank) skills.
+ *
+ * Cosine is computed inline (no extra dep). The formula's denominator
+ * guards against zero-norm vectors by `|| 1` — that turns a degenerate
+ * "embedded the empty string" case into a 0 score rather than NaN.
+ */
+export async function prefilterSkills(taskSubject, skills, opts = {}) {
+    if (skills.length === 0)
+        return [];
+    const k = opts.k ?? 10;
+    const cache = opts.cache ?? new Map();
+    const ollamaUrl = opts.ollamaUrl ?? 'http://localhost:11434';
+    let subjectVec;
+    try {
+        subjectVec = await ollamaEmbed(ollamaUrl, taskSubject);
+    }
+    catch {
+        // Embedder dead — degrade to "load everything" and let the router
+        // (or the dispatcher) handle filtering downstream.
+        return skills;
+    }
+    const scored = [];
+    for (const s of skills) {
+        // `prose` is optional on Skill; fall back to `name` so we always
+        // have something to embed. Skill name is a weak signal — the risk
+        // callout in the task spec notes this; production packs should
+        // author prose.
+        const desc = s.prose ?? s.name;
+        let vec = cache.get(desc);
+        if (!vec) {
+            try {
+                vec = await ollamaEmbed(ollamaUrl, desc);
+                cache.set(desc, vec);
+            }
+            catch {
+                // Skip this skill; continue ranking the rest. A flaky per-skill
+                // failure shouldn't wipe the whole shortlist.
+                continue;
+            }
+        }
+        scored.push({ skill: s, score: cosine(subjectVec, vec) });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, k).map((x) => x.skill);
+}
+/**
+ * Cosine similarity between two equal-length numeric vectors.
+ *
+ * No extra dep — implemented inline per acceptance criterion. Vectors
+ * are assumed to be the same dimension (Qwen3 2560 in production); a
+ * length mismatch would silently truncate to `a.length`. That's the
+ * embedder's contract responsibility, not this function's: every
+ * `ollamaEmbed` call against the same model returns the same dim.
+ */
+function cosine(a, b) {
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        const ai = a[i] ?? 0;
+        const bi = b[i] ?? 0;
+        dot += ai * bi;
+        na += ai * ai;
+        nb += bi * bi;
+    }
+    // `|| 1` short-circuits the zero-norm degenerate case to 0 (via dot=0
+    // when one of the vectors is all-zeros) rather than NaN.
+    return dot / (Math.sqrt(na) * Math.sqrt(nb) || 1);
+}
+//# sourceMappingURL=skill_prefilter.js.map

package/dist/runtime/skill_prefilter.js.map

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

package/dist/runtime/skill_requires.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `Skill.requires:` AND-semantic precondition evaluator (T-ASC, ASC.2).
+ *
+ * Slots into the dispatcher between `matchesEvent` (per-skill activation
+ * filter) and the rule walk. AND-semantics: every entry must hold; empty
+ * array trivially holds (back-compat with every existing skill).
+ *
+ * Precondition kinds (discriminated-union by `kind`):
+ *   automation_mode_on  — stat `<home>/sessions/<id>/automation.flag`
+ *   active_task_present — stat `<home>/sessions/<id>/active-task.json`
+ * (The former `chain_stage` precondition was removed with chain_state — a pack
+ *  now gates on lifecycle state directly via the `read_fsm_state` primitive in
+ *  a rule `if:`. See T-WORKFLOW-AS-PACK-FSM.)
+ *
+ * Fail-open in the engaged direction (T-ASC L5 / L6 lock): any stat error
+ * OTHER than ENOENT (EACCES, EPERM, EIO, EROFS, …) ⇒ assume engaged, return
+ * true. Wrong direction would silently disable every personal-pack skill on
+ * a `chmod 000 ~/.opensquid` event. The probe's contract: TRUE (= present /
+ * engaged) is the default for uncertainty.
+ *
+ * Per-fire cache (L6): the dispatcher constructs ONE `RequiresCache` per
+ * `dispatchEvent` call and threads it to every `skillRequiresHold` invocation
+ * across all loaded skills. N skills sharing `automation_mode_on` stat the
+ * flag ONCE per fire. The cache is per-CALL, NEVER module-level — hook bins
+ * are short-lived processes; long-lived state would cross process boundaries
+ * meaninglessly.
+ *
+ * Imports from: node:fs/promises, zod, ./automation_state.js, ./paths.js.
+ * Imported by: src/packs/schemas/skill.ts (the Skill schema's `requires:`
+ *   field type), src/runtime/types.ts (the runtime type mirror),
+ *   src/runtime/hooks/dispatch.ts (the dispatcher integration point).
+ */
+import { z } from 'zod';
+/**
+ * SkillRequires variant. Discriminated by `kind`. Adding a new precondition
+ * kind means adding a variant here AND a branch in `skillRequiresHold`'s
+ * switch AND a getter on `RequiresCache`. Exhaustiveness is enforced by
+ * TypeScript narrowing in the switch.
+ */
+export declare const SkillRequires: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"automation_mode_on">;
+}, "strict", z.ZodTypeAny, {
+    kind: "automation_mode_on";
+}, {
+    kind: "automation_mode_on";
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"active_task_present">;
+}, "strict", z.ZodTypeAny, {
+    kind: "active_task_present";
+}, {
+    kind: "active_task_present";
+}>]>;
+export type SkillRequires = z.infer<typeof SkillRequires>;
+/**
+ * Per-fire cache. The dispatcher constructs ONE instance per `dispatchEvent`
+ * call. One map per precondition kind, keyed by sessionId (each precondition's
+ * single relevant input), so N skills sharing a kind probe disk ONCE per fire.
+ *
+ * Strictly avoid making this a module-level cache: hook bins are short-lived
+ * processes (one per host event) and per-call caching is the right scope.
+ */
+export declare class RequiresCache {
+    private readonly automation;
+    private readonly activeTask;
+    automationModeOn(sessionId: string): Promise<boolean>;
+    activeTaskPresent(sessionId: string): Promise<boolean>;
+}
+/**
+ * AND-evaluate every precondition. Empty array → trivially true (back-compat
+ * with every Phase 1+ pack). Short-circuits on first false: skills that
+ * declare multiple preconditions don't pay for later checks once one fails.
+ *
+ * The exhaustive switch keeps TypeScript narrowing — adding a new variant
+ * to `SkillRequires` without adding a case here is a typecheck error.
+ */
+export declare function skillRequiresHold(preconds: readonly SkillRequires[], sessionId: string, cache: RequiresCache): Promise<boolean>;
+//# sourceMappingURL=skill_requires.d.ts.map

package/dist/runtime/skill_requires.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill_requires.d.ts","sourceRoot":"","sources":["../../src/runtime/skill_requires.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;IAGxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8B;IACzD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8B;IAEnD,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQrD,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAO7D;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,OAAO,CAAC,CAmBlB"}

package/dist/runtime/skill_requires.js

@@ -0,0 +1,124 @@
+/**
+ * `Skill.requires:` AND-semantic precondition evaluator (T-ASC, ASC.2).
+ *
+ * Slots into the dispatcher between `matchesEvent` (per-skill activation
+ * filter) and the rule walk. AND-semantics: every entry must hold; empty
+ * array trivially holds (back-compat with every existing skill).
+ *
+ * Precondition kinds (discriminated-union by `kind`):
+ *   automation_mode_on  — stat `<home>/sessions/<id>/automation.flag`
+ *   active_task_present — stat `<home>/sessions/<id>/active-task.json`
+ * (The former `chain_stage` precondition was removed with chain_state — a pack
+ *  now gates on lifecycle state directly via the `read_fsm_state` primitive in
+ *  a rule `if:`. See T-WORKFLOW-AS-PACK-FSM.)
+ *
+ * Fail-open in the engaged direction (T-ASC L5 / L6 lock): any stat error
+ * OTHER than ENOENT (EACCES, EPERM, EIO, EROFS, …) ⇒ assume engaged, return
+ * true. Wrong direction would silently disable every personal-pack skill on
+ * a `chmod 000 ~/.opensquid` event. The probe's contract: TRUE (= present /
+ * engaged) is the default for uncertainty.
+ *
+ * Per-fire cache (L6): the dispatcher constructs ONE `RequiresCache` per
+ * `dispatchEvent` call and threads it to every `skillRequiresHold` invocation
+ * across all loaded skills. N skills sharing `automation_mode_on` stat the
+ * flag ONCE per fire. The cache is per-CALL, NEVER module-level — hook bins
+ * are short-lived processes; long-lived state would cross process boundaries
+ * meaninglessly.
+ *
+ * Imports from: node:fs/promises, zod, ./automation_state.js, ./paths.js.
+ * Imported by: src/packs/schemas/skill.ts (the Skill schema's `requires:`
+ *   field type), src/runtime/types.ts (the runtime type mirror),
+ *   src/runtime/hooks/dispatch.ts (the dispatcher integration point).
+ */
+import { stat } from 'node:fs/promises';
+import { z } from 'zod';
+import { automationFlagPath } from './automation_state.js';
+import { activeTaskFile } from './paths.js';
+/**
+ * SkillRequires variant. Discriminated by `kind`. Adding a new precondition
+ * kind means adding a variant here AND a branch in `skillRequiresHold`'s
+ * switch AND a getter on `RequiresCache`. Exhaustiveness is enforced by
+ * TypeScript narrowing in the switch.
+ */
+export const SkillRequires = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('automation_mode_on') }).strict(),
+    z.object({ kind: z.literal('active_task_present') }).strict(),
+]);
+/**
+ * Per-fire cache. The dispatcher constructs ONE instance per `dispatchEvent`
+ * call. One map per precondition kind, keyed by sessionId (each precondition's
+ * single relevant input), so N skills sharing a kind probe disk ONCE per fire.
+ *
+ * Strictly avoid making this a module-level cache: hook bins are short-lived
+ * processes (one per host event) and per-call caching is the right scope.
+ */
+export class RequiresCache {
+    automation = new Map();
+    activeTask = new Map();
+    async automationModeOn(sessionId) {
+        const cached = this.automation.get(sessionId);
+        if (cached !== undefined)
+            return cached;
+        const present = await probePresent(automationFlagPath(sessionId));
+        this.automation.set(sessionId, present);
+        return present;
+    }
+    async activeTaskPresent(sessionId) {
+        const cached = this.activeTask.get(sessionId);
+        if (cached !== undefined)
+            return cached;
+        const present = await probePresent(activeTaskFile(sessionId));
+        this.activeTask.set(sessionId, present);
+        return present;
+    }
+}
+/**
+ * AND-evaluate every precondition. Empty array → trivially true (back-compat
+ * with every Phase 1+ pack). Short-circuits on first false: skills that
+ * declare multiple preconditions don't pay for later checks once one fails.
+ *
+ * The exhaustive switch keeps TypeScript narrowing — adding a new variant
+ * to `SkillRequires` without adding a case here is a typecheck error.
+ */
+export async function skillRequiresHold(preconds, sessionId, cache) {
+    for (const p of preconds) {
+        switch (p.kind) {
+            case 'automation_mode_on':
+                if (!(await cache.automationModeOn(sessionId)))
+                    return false;
+                break;
+            case 'active_task_present':
+                if (!(await cache.activeTaskPresent(sessionId)))
+                    return false;
+                break;
+            default: {
+                // Exhaustiveness check — TS narrows `p` to `never` here when every
+                // variant has a case above. Adding a new SkillRequires variant
+                // without a case lights up at compile time.
+                const _exhaustive = p;
+                return _exhaustive;
+            }
+        }
+    }
+    return true;
+}
+/**
+ * Stat probe with fail-open semantics in the engaged direction.
+ *   - clean ENOENT → false (absent: the gate may treat as "not engaged")
+ *   - any other error (EACCES/EPERM/EIO/EROFS/…) → true (assume engaged;
+ *     never silently swallow a gate over a permissions/IO blip inside a
+ *     short-lived hook bin)
+ *   - successful stat → true (present)
+ */
+async function probePresent(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return false;
+        return true;
+    }
+}
+//# sourceMappingURL=skill_requires.js.map

package/dist/runtime/skill_requires.js.map

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

package/dist/runtime/skill_router.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Model-aliased skill router (Phase 3 Task 3.4).
+ *
+ * Purpose: take the embedder-shortlisted candidate skills (output of
+ * `prefilterSkills`) and ask a fast classifier LLM which subset is
+ * actually needed for the current task. Returns the filtered skill
+ * list. This is the second tier of the two-tier dynamic-load pipeline
+ * — the embedder is high-recall / low-precision; the classifier is
+ * the precision step.
+ *
+ * Model neutrality (per `feedback_stop_haiku_drift` +
+ * `project_opensquid_model_neutral_subagent_primitive`): we route via
+ * the `fast_classifier` ALIAS, never a vendor model name. The user's
+ * `models.yaml` maps the alias to whichever subscription CLI or API
+ * binding they prefer. No model id ever appears in this file.
+ *
+ * Prompt shape — a tight classification prompt with three rules:
+ *   1. Task subject up front (top-of-context bias).
+ *   2. Skills listed with `name: prose` so the classifier sees what
+ *      each skill is FOR, not just the bare ids.
+ *   3. Output instruction is comma-separated names OR the `NONE` token.
+ *      `llm_classify` itself clamps unknown outputs to `UNCERTAIN`, so
+ *      we treat both `UNCERTAIN` and `NONE` as the safety fallback.
+ *
+ * Failure ladder ("fail safe-ward" — toward more skills, never fewer):
+ *   - classifier errors / not-ok      → return ALL candidates
+ *   - classifier returns UNCERTAIN    → return ALL candidates
+ *   - classifier returns NONE         → return ALL candidates
+ *   - classifier returns "a, b, c"    → return matching candidates
+ *
+ * The NONE/UNCERTAIN cases biasing toward "load everything" matches
+ * the prefilter's fail-open contract: this layer is an optimization,
+ * never a gate. A drifting classifier should never lock the agent out
+ * of a needed skill. The cost of a false-positive (loading a skill
+ * we didn't strictly need) is context dilution; the cost of a
+ * false-negative (omitting a needed skill) is a missed verification
+ * pass. Phase 3 picks the former.
+ *
+ * Imports from: ../functions/registry.js (FunctionRegistry + EvalCtx),
+ *   ./types.js (Skill).
+ * Imported by: src/runtime/index.ts (re-exported as `routeSkills`)
+ *   and the dispatcher pipeline once Phase 3 wiring lands.
+ */
+import type { EvalCtx, FunctionRegistry } from '../functions/registry.js';
+import type { Skill } from './types.js';
+/**
+ * Ask the `fast_classifier`-aliased LLM which of `candidates` are
+ * needed for `taskSubject`. Returns a filtered subset of `candidates`,
+ * or — under any fallback condition — the full `candidates` list.
+ *
+ * `registry` must have `llm_classify` registered (the LLM primitive
+ * from `src/functions/llm.ts`). `ctx` is forwarded verbatim; the
+ * primitive uses only its model dispatcher, not the bindings or event,
+ * so any well-formed `EvalCtx` works.
+ */
+export declare function routeSkills(taskSubject: string, candidates: Skill[], registry: FunctionRegistry, ctx: EvalCtx): Promise<Skill[]>;
+//# sourceMappingURL=skill_router.d.ts.map

package/dist/runtime/skill_router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill_router.d.ts","sourceRoot":"","sources":["../../src/runtime/skill_router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE1E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,KAAK,EAAE,EACnB,QAAQ,EAAE,gBAAgB,EAC1B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,KAAK,EAAE,CAAC,CAkDlB"}

package/dist/runtime/skill_router.js

@@ -0,0 +1,97 @@
+/**
+ * Model-aliased skill router (Phase 3 Task 3.4).
+ *
+ * Purpose: take the embedder-shortlisted candidate skills (output of
+ * `prefilterSkills`) and ask a fast classifier LLM which subset is
+ * actually needed for the current task. Returns the filtered skill
+ * list. This is the second tier of the two-tier dynamic-load pipeline
+ * — the embedder is high-recall / low-precision; the classifier is
+ * the precision step.
+ *
+ * Model neutrality (per `feedback_stop_haiku_drift` +
+ * `project_opensquid_model_neutral_subagent_primitive`): we route via
+ * the `fast_classifier` ALIAS, never a vendor model name. The user's
+ * `models.yaml` maps the alias to whichever subscription CLI or API
+ * binding they prefer. No model id ever appears in this file.
+ *
+ * Prompt shape — a tight classification prompt with three rules:
+ *   1. Task subject up front (top-of-context bias).
+ *   2. Skills listed with `name: prose` so the classifier sees what
+ *      each skill is FOR, not just the bare ids.
+ *   3. Output instruction is comma-separated names OR the `NONE` token.
+ *      `llm_classify` itself clamps unknown outputs to `UNCERTAIN`, so
+ *      we treat both `UNCERTAIN` and `NONE` as the safety fallback.
+ *
+ * Failure ladder ("fail safe-ward" — toward more skills, never fewer):
+ *   - classifier errors / not-ok      → return ALL candidates
+ *   - classifier returns UNCERTAIN    → return ALL candidates
+ *   - classifier returns NONE         → return ALL candidates
+ *   - classifier returns "a, b, c"    → return matching candidates
+ *
+ * The NONE/UNCERTAIN cases biasing toward "load everything" matches
+ * the prefilter's fail-open contract: this layer is an optimization,
+ * never a gate. A drifting classifier should never lock the agent out
+ * of a needed skill. The cost of a false-positive (loading a skill
+ * we didn't strictly need) is context dilution; the cost of a
+ * false-negative (omitting a needed skill) is a missed verification
+ * pass. Phase 3 picks the former.
+ *
+ * Imports from: ../functions/registry.js (FunctionRegistry + EvalCtx),
+ *   ./types.js (Skill).
+ * Imported by: src/runtime/index.ts (re-exported as `routeSkills`)
+ *   and the dispatcher pipeline once Phase 3 wiring lands.
+ */
+/**
+ * Ask the `fast_classifier`-aliased LLM which of `candidates` are
+ * needed for `taskSubject`. Returns a filtered subset of `candidates`,
+ * or — under any fallback condition — the full `candidates` list.
+ *
+ * `registry` must have `llm_classify` registered (the LLM primitive
+ * from `src/functions/llm.ts`). `ctx` is forwarded verbatim; the
+ * primitive uses only its model dispatcher, not the bindings or event,
+ * so any well-formed `EvalCtx` works.
+ */
+export async function routeSkills(taskSubject, candidates, registry, ctx) {
+    if (candidates.length === 0)
+        return [];
+    // Allowed labels = the candidate names plus NONE. `llm_classify`
+    // already injects UNCERTAIN as the clamp value for unmatched output,
+    // so we don't list it in allowed_labels (the underlying primitive
+    // returns 'UNCERTAIN' literally when nothing matches).
+    const labels = [...candidates.map((s) => s.name), 'NONE'];
+    // Prompt shape: subject first, candidate list with `name: prose`,
+    // strict output instruction at the bottom. `prose ?? name` mirrors
+    // the prefilter's weak-fallback path so descriptions stay consistent
+    // across the two-tier pipeline.
+    const prompt = [
+        `Task: ${taskSubject}`,
+        `Which of the following skills are needed?`,
+        `Skills:\n${candidates.map((s) => `${s.name}: ${s.prose ?? s.name}`).join('\n')}`,
+        `Respond with comma-separated skill names, or NONE.`,
+    ].join('\n');
+    const result = await registry.call('llm_classify', {
+        model: 'fast_classifier',
+        prompt,
+        allowed_labels: labels,
+    }, ctx);
+    // Classifier errored at the primitive level (unknown alias, etc.) —
+    // fall through to all candidates. `llm_classify` itself never throws,
+    // but it CAN return `err({kind:'arg_invalid'})` if `fast_classifier`
+    // isn't mapped in the user's models.yaml.
+    if (!result.ok)
+        return candidates;
+    const choice = String(result.value);
+    // Both safety sentinels collapse to "load everything." UNCERTAIN
+    // comes from the llm_classify clamp on unmatched output; NONE comes
+    // from the model itself saying "I see no fit". Either way, do not
+    // strand the agent without skills.
+    if (choice === 'UNCERTAIN' || choice === 'NONE')
+        return candidates;
+    // Parse the comma-separated list, trim each token, and intersect
+    // with the candidate set by `name`. Tokens that don't match a
+    // candidate are silently dropped — the classifier may hallucinate a
+    // name and we'd rather return nothing-extra than crash.
+    const names = new Set(choice.split(',').map((s) => s.trim()));
+    return candidates.filter((s) => names.has(s.name));
+}
+//# sourceMappingURL=skill_router.js.map

package/dist/runtime/skill_router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill_router.js","sourceRoot":"","sources":["../../src/runtime/skill_router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAMH;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,WAAmB,EACnB,UAAmB,EACnB,QAA0B,EAC1B,GAAY;IAEZ,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEvC,iEAAiE;IACjE,qEAAqE;IACrE,kEAAkE;IAClE,uDAAuD;IACvD,MAAM,MAAM,GAAG,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;IAE1D,kEAAkE;IAClE,mEAAmE;IACnE,qEAAqE;IACrE,gCAAgC;IAChC,MAAM,MAAM,GAAG;QACb,SAAS,WAAW,EAAE;QACtB,2CAA2C;QAC3C,YAAY,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QACjF,oDAAoD;KACrD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAChC,cAAc,EACd;QACE,KAAK,EAAE,iBAAiB;QACxB,MAAM;QACN,cAAc,EAAE,MAAM;KACvB,EACD,GAAG,CACJ,CAAC;IAEF,oEAAoE;IACpE,sEAAsE;IACtE,qEAAqE;IACrE,0CAA0C;IAC1C,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,UAAU,CAAC;IAElC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAEpC,iEAAiE;IACjE,oEAAoE;IACpE,kEAAkE;IAClE,mCAAmC;IACnC,IAAI,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,UAAU,CAAC;IAEnE,iEAAiE;IACjE,8DAA8D;IAC9D,oEAAoE;IACpE,wDAAwD;IACxD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC9D,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACrD,CAAC"}

package/dist/runtime/tick.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Tick driver — pure data layer for the `unloads_when` evaluator.
+ *
+ * The runtime maintains one `TickState` per active skill. As Events flow
+ * through the dispatcher, `advanceTick` updates that state so the evaluator
+ * (`unload_conditions.ts`) can answer "should this skill unload?" without
+ * the dispatcher having to bake event-shape knowledge into every check.
+ *
+ * Authoritative source: `docs/opensquid-real-design.md` §"Skill format" +
+ * memory `feedback_workflow_cycle` (turn = UserPromptSubmit cycle).
+ *
+ * Turn definition — pinned: a "turn" is ONE UserPromptSubmit event. Tool
+ * calls inside that turn do NOT increment the counter. This matches the
+ * 7-phase workflow loop (pre-research → learn → code → test → audit →
+ * post-research → fix), where the boundary that matters for "idle" is
+ * "did the user say anything new" — not "did the agent run a tool."
+ *
+ * State transitions per Event kind:
+ *
+ *   prompt_submit                            → turnsSinceActivation += 1
+ *   stop                                     → taskCompleted = true
+ *   session_end                              → sessionEnded = true
+ *   tool_call                                → no-op (sub-event of a turn)
+ *   schedule | webhook | inbound_channel |   → no-op (AUTO.1 trigger sources
+ *   file_changed                              fire outside the prompt-submit
+ *                                             turn cycle and don't mutate
+ *                                             user-facing tick state)
+ *
+ * `resetTick` puts a fresh state on the wire when a skill (re)activates —
+ * the counters apply from that point forward, not from session start.
+ *
+ * Pure data, no I/O. Returns a NEW object on each `advanceTick` call so the
+ * dispatcher can keep prior snapshots around if it wants (e.g. for diagnostic
+ * dumps). The evaluator reads the latest snapshot.
+ *
+ * Imports from: ./types, ./unload_conditions.
+ * Imported by: src/runtime/index.ts; (eventually) the dispatcher.
+ */
+import type { Event } from './types.js';
+import type { TickState } from './unload_conditions.js';
+export declare function createTick(): TickState;
+export declare function advanceTick(state: Readonly<TickState>, event: Event): TickState;
+export declare function resetTick(): TickState;
+//# sourceMappingURL=tick.d.ts.map

package/dist/runtime/tick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tick.d.ts","sourceRoot":"","sources":["../../src/runtime/tick.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAMxD,wBAAgB,UAAU,IAAI,SAAS,CAEtC;AAUD,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,SAAS,CAsC/E;AAQD,wBAAgB,SAAS,IAAI,SAAS,CAErC"}