opensquid 0.5.395

package/dist/functions/lessons.js

@@ -0,0 +1,241 @@
+/**
+ * Lesson primitives: `propose_lesson`, `promote_lesson`, `recall_lesson`.
+ *
+ * T-loop-engine-reintegration T.6 — surfaces the loop-engine wedge gate
+ * to skills. Three atomic primitives compose into capture/promote/recall
+ * workflows; the gate itself lives in `engine/src/engine/lessons/gate.rs`.
+ *
+ * Why these three (and only these three):
+ *   - `propose_lesson` — the capture surface. Skill authors call this
+ *     when an agent or user proposes a new lesson candidate. Agent-
+ *     authored lessons remain `pending` until the gate promotes them;
+ *     user-authored lessons skip the gate (eviction-immune via
+ *     `Authorship::is_immune` per T.1.G).
+ *   - `promote_lesson` — the gate firing surface. Calls engine's
+ *     `lesson.promote`, which runs the wedge checks. A block here is
+ *     the entire competitive moat (per
+ *     `project_2026_05_12_strategic_pivot`): the only system that
+ *     refuses to self-grade promotions. We surface the block as a
+ *     successful `ok({status:'blocked', reasons})` because the block IS
+ *     the system working as designed — not a runtime error.
+ *   - `recall_lesson` — text-match retrieval across pending/active/
+ *     promoted/superseded status dirs (T.1.B). NOT vector — that
+ *     property surfaces evidence-less lessons during the capture loop
+ *     even when the embedder is degraded.
+ *
+ * What's intentionally NOT here (out of scope; pack-install only):
+ *   - `pack_id`, `external_id`, `seed_as_promoted` on propose_lesson —
+ *     pack-authored seed paths handled by a separate install flow
+ *     (T.1.B notes the validation rules: `pack_id` required when
+ *     `authored_by === 'pack'`, `seed_as_promoted` requires
+ *     `authored_by === 'pack'`).
+ *
+ * Authored_by encoding gotcha (T.1.G):
+ *   The wire input only honors `'user'` and `'pack'`. Anything else —
+ *   including `'agent'` from a Zod-validated arg — silently maps to
+ *   engine's `Llm` default. We accept `'user' | 'agent'` from skill
+ *   authors for ergonomic symmetry with the existing `store_lesson`
+ *   primitive, then translate: `'user'` passes through verbatim;
+ *   `'agent'` becomes `undefined` (engine default Llm). User-authored
+ *   lessons are eviction-immune; agent/llm-authored aren't.
+ *
+ * Why no "permits promotion" test (deliberate scope correction per
+ * T.1.F + T.1.HH + spec line 967-969):
+ *   The engine's `PromotionConfig::default()` requires:
+ *     min_age = 24 hours
+ *     min_applied_count = 3 (via manifest.assemble side effect)
+ *     external_signal_sources non-empty (via lesson.capture_feedback)
+ *     causal_narrative present (auto-built when evidence is supplied)
+ *   None of those are satisfiable in unit-test timescales — that's the
+ *   moat working as designed, not a bug. T.6 proves the gate FIRES
+ *   (block-only E2E); production promotion only happens over real
+ *   session usage. T.8 will file an engine follow-up to expose a
+ *   PromotionConfig override for testing, but that's NOT in T.6 scope.
+ *
+ * Imports from: zod, ../engine/client.js, ../engine/types.js,
+ *   ../runtime/result.js, ./registry.js.
+ * Imported by: ../runtime/bootstrap.ts.
+ */
+import { z } from 'zod';
+import { err, ok } from '../runtime/result.js';
+import { PromotionBlockedError } from '../rag/wedge/store.js';
+// ---------------------------------------------------------------------------
+// Zod arg schemas.
+//
+// `description` / `body` get `min(1)` to block empty-string foot-guns. The
+// engine would reject empty strings too, but the Zod check surfaces the
+// problem at the function-call boundary (cleaner error path than a JSON-RPC
+// round-trip).
+//
+// `authored_by` accepts the human-friendly `'user' | 'agent'` enum. The
+// 'agent' value is translated to engine's wire-level default (Llm) inside
+// execute(); see the file header for the rationale.
+//
+// `recall_lesson.limit` is bounded to [1, 50] — engine doesn't enforce an
+// upper bound itself, but a 1000-row dump from a YAML wiring bug is more
+// likely than a real need for >50 lesson hits.
+// ---------------------------------------------------------------------------
+const ProposeLessonArgs = z.object({
+    description: z.string().min(1),
+    body: z.string().min(1),
+    evidence: z.array(z.string()).optional(),
+    authored_by: z.enum(['user', 'agent']).optional(),
+    // pack_id / external_id / seed_as_promoted intentionally NOT exposed here.
+    // Those are pack-install-only paths handled separately (see header).
+});
+const PromoteLessonArgs = z.object({
+    id: z.string().min(1),
+});
+const RecallLessonArgs = z.object({
+    query: z.string().min(1),
+    limit: z.number().int().min(1).max(50).optional(),
+});
+export function registerLessonFunctions(registry, store) {
+    // DURABLE.2 — all three primitives touch the loop-engine UDS. `propose` and
+    // `promote` are durable side-effecting writes (re-running on resume creates
+    // a duplicate lesson or re-fires the gate). They are NOT memoizable —
+    // memoizing a write would silently no-op the second insert. `recall` is
+    // durable + memoizable (text-match output is deterministic for the same
+    // query within a bounded TTL — the in-memory memo cache picks up the
+    // repeat). All flags declared explicitly so the registry's `durable`
+    // omission warning stays quiet.
+    registry.register({
+        name: 'propose_lesson',
+        argSchema: ProposeLessonArgs,
+        durable: true,
+        memoizable: false,
+        costEstimateMs: 30,
+        execute: async (args) => {
+            try {
+                // Only 'user' propagates (user-authored lessons are eviction-immune);
+                // 'agent' is the store default. `exactOptionalPropertyTypes` → OMIT.
+                const r = await store.createLesson({
+                    description: args.description,
+                    body: args.body,
+                    ...(args.evidence && args.evidence.length > 0 ? { evidenceRefs: args.evidence } : {}),
+                    ...(args.authored_by === 'user' ? { authoredBy: 'user' } : {}),
+                });
+                return ok({ id: r.id, status: r.status });
+            }
+            catch (e) {
+                return err({
+                    kind: 'runtime',
+                    message: `propose_lesson: ${String(e)}`,
+                    cause: e,
+                });
+            }
+        },
+    });
+    /**
+     * `promote_lesson` returns two `status` cases — branch deterministically.
+     *
+     * Usage from a YAML skill:
+     *
+     * ```yaml
+     * process:
+     *   - function: promote_lesson
+     *     args: { id: "{lesson_id}" }
+     *     bind: result
+     * verdict: |
+     *   if (result.status === "blocked") return { kind: "block", reasons: result.reasons };
+     *   return { kind: "promote" };
+     * ```
+     *
+     * `status: 'blocked'` means the wedge gate fired (moat working as
+     * designed — NOT an error). `kind: 'runtime'` on the Result envelope
+     * means a genuine infra failure (engine unreachable, etc.).
+     */
+    registry.register({
+        name: 'promote_lesson',
+        argSchema: PromoteLessonArgs,
+        durable: true,
+        memoizable: false,
+        costEstimateMs: 50,
+        execute: async (args) => {
+            try {
+                const r = await store.promoteLesson(args.id);
+                return ok({ status: 'promoted', detail: r });
+            }
+            catch (e) {
+                // A gate block surfaces as PromotionBlockedError with kebab-prefix
+                // reasons. This is the wedge moat firing — NOT a runtime error —
+                // so surface it as a successful Result with `status: 'blocked'`
+                // (skills branch on the field). (The engine-era compression hook
+                // that nominated cited memories on promotion is dropped here; that
+                // coupling moves to the compression port, RES-4.)
+                if (e instanceof PromotionBlockedError) {
+                    return ok({ status: 'blocked', reasons: e.reasons });
+                }
+                return err({
+                    kind: 'runtime',
+                    message: `promote_lesson: ${String(e)}`,
+                    cause: e,
+                });
+            }
+        },
+    });
+    registry.register({
+        name: 'recall_lesson',
+        argSchema: RecallLessonArgs,
+        durable: true,
+        memoizable: true,
+        costEstimateMs: 50,
+        execute: async (args) => {
+            try {
+                // Text-match (FTS) across non-discarded statuses. `limit` defaults to
+                // 5 in the store when omitted.
+                return ok(await store.recallLesson(args.query, args.limit));
+            }
+            catch (e) {
+                return err({
+                    kind: 'runtime',
+                    message: `recall_lesson: ${String(e)}`,
+                    cause: e,
+                });
+            }
+        },
+    });
+    // capture_feedback + record_applied — the two in-process surfaces the wedge
+    // gate needs to ever PROMOTE: the DEFAULT gate requires a non-empty
+    // external_signal_sources (fed by capture_feedback) AND applied_count >= 3
+    // (fed by record_applied). The engine fed these via its feedback RPC +
+    // manifest.assemble; in-process both must be reachable or promotion is
+    // unsatisfiable.
+    registry.register({
+        name: 'capture_feedback',
+        argSchema: z.object({
+            id: z.string().min(1),
+            polarity: z.enum(['up', 'down']),
+            signal_id: z.string().min(1),
+        }),
+        durable: true,
+        memoizable: false,
+        costEstimateMs: 20,
+        execute: async (args) => {
+            try {
+                await store.captureFeedback(args.id, args.polarity, args.signal_id);
+                return ok({ id: args.id });
+            }
+            catch (e) {
+                return err({ kind: 'runtime', message: `capture_feedback: ${String(e)}`, cause: e });
+            }
+        },
+    });
+    registry.register({
+        name: 'record_applied',
+        argSchema: z.object({ id: z.string().min(1), session_id: z.string().optional() }),
+        durable: true,
+        memoizable: false,
+        costEstimateMs: 20,
+        execute: async (args) => {
+            try {
+                await store.recordApplied(args.id, args.session_id);
+                return ok({ id: args.id });
+            }
+            catch (e) {
+                return err({ kind: 'runtime', message: `record_applied: ${String(e)}`, cause: e });
+            }
+        },
+    });
+}
+//# sourceMappingURL=lessons.js.map

package/dist/functions/lessons.js.map

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

package/dist/functions/llm.d.ts

@@ -0,0 +1,44 @@
+/**
+ * LLM primitives: `subagent_call` + `llm_classify`. Skills compose these
+ * into rule processes via YAML; the runtime dispatches each call through
+ * the model dispatcher to whichever backend the user's `models.yaml`
+ * mapped the alias to.
+ *
+ * Model neutrality (per `project_opensquid_model_neutral_subagent_primitive`
+ * and the model-name-drift feedback memory): packs say `model:
+ * fast_classifier`, never a vendor model id. Vendor identity lives in
+ * user config. This file names no vendors and the dispatch path is
+ * identical for every backend.
+ *
+ * Primitives:
+ *
+ *   subagent_call({ model, prompt, timeout_ms? }) → ok(stdout) | err
+ *     Calls the strategy and returns its raw output. The only failure
+ *     surfaces are `arg_invalid` (unknown alias) and `runtime` (spawn /
+ *     timeout / non-zero exit). Use this when the pack needs the full
+ *     model response — narrative generation, structured-output tasks,
+ *     long-form reasoning.
+ *
+ *   llm_classify({ model, prompt, allowed_labels, timeout_ms? }) → ok(label)
+ *     Wraps `prompt` with a "respond with exactly one of …" suffix, calls
+ *     the strategy, takes the first whitespace-delimited token of the
+ *     output, and case-insensitively matches it against `allowed_labels`.
+ *     Returns `ok('UNCERTAIN')` if no match — and crucially, also clamps
+ *     to `'UNCERTAIN'` on EVERY thrown error (timeout, spawn failure,
+ *     non-zero exit). A classifier that throws would force every caller
+ *     to wrap try/catch; clamping keeps the pack YAML simple. The cost
+ *     is that real misconfiguration (alias points at a dead binary)
+ *     looks the same as "model couldn't decide" — auditors should grep
+ *     for the `'UNCERTAIN'` rate to catch that.
+ *
+ *   The one `arg_invalid` exception (unknown alias) is intentional:
+ *   that's a config error, not a classifier judgment, and it should
+ *   surface loudly so the user fixes their `models.yaml`.
+ *
+ * Imports from: zod, ../runtime/result.js, ../models/dispatcher.js,
+ *   ../models/load_config.js, ./registry.js.
+ * Imported by: src/functions/index.ts.
+ */
+import type { FunctionRegistry } from './registry.js';
+export declare function registerLlmFunctions(registry: FunctionRegistry): void;
+//# sourceMappingURL=llm.d.ts.map

package/dist/functions/llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/functions/llm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAQH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AA6BtD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CA4FrE"}

package/dist/functions/llm.js

@@ -0,0 +1,160 @@
+/**
+ * LLM primitives: `subagent_call` + `llm_classify`. Skills compose these
+ * into rule processes via YAML; the runtime dispatches each call through
+ * the model dispatcher to whichever backend the user's `models.yaml`
+ * mapped the alias to.
+ *
+ * Model neutrality (per `project_opensquid_model_neutral_subagent_primitive`
+ * and the model-name-drift feedback memory): packs say `model:
+ * fast_classifier`, never a vendor model id. Vendor identity lives in
+ * user config. This file names no vendors and the dispatch path is
+ * identical for every backend.
+ *
+ * Primitives:
+ *
+ *   subagent_call({ model, prompt, timeout_ms? }) → ok(stdout) | err
+ *     Calls the strategy and returns its raw output. The only failure
+ *     surfaces are `arg_invalid` (unknown alias) and `runtime` (spawn /
+ *     timeout / non-zero exit). Use this when the pack needs the full
+ *     model response — narrative generation, structured-output tasks,
+ *     long-form reasoning.
+ *
+ *   llm_classify({ model, prompt, allowed_labels, timeout_ms? }) → ok(label)
+ *     Wraps `prompt` with a "respond with exactly one of …" suffix, calls
+ *     the strategy, takes the first whitespace-delimited token of the
+ *     output, and case-insensitively matches it against `allowed_labels`.
+ *     Returns `ok('UNCERTAIN')` if no match — and crucially, also clamps
+ *     to `'UNCERTAIN'` on EVERY thrown error (timeout, spawn failure,
+ *     non-zero exit). A classifier that throws would force every caller
+ *     to wrap try/catch; clamping keeps the pack YAML simple. The cost
+ *     is that real misconfiguration (alias points at a dead binary)
+ *     looks the same as "model couldn't decide" — auditors should grep
+ *     for the `'UNCERTAIN'` rate to catch that.
+ *
+ *   The one `arg_invalid` exception (unknown alias) is intentional:
+ *   that's a config error, not a classifier judgment, and it should
+ *   surface loudly so the user fixes their `models.yaml`.
+ *
+ * Imports from: zod, ../runtime/result.js, ../models/dispatcher.js,
+ *   ../models/load_config.js, ./registry.js.
+ * Imported by: src/functions/index.ts.
+ */
+import { z } from 'zod';
+import { loadModelsConfig } from '../models/load_config.js';
+import { resolveStrategy } from '../models/dispatcher.js';
+import { err, ok } from '../runtime/result.js';
+// ---------------------------------------------------------------------------
+// Zod arg schemas.
+//
+// `model` / `prompt` get `min(1)` to block empty-string foot-guns; the empty
+// prompt is almost certainly a YAML typo (someone referenced a binding that
+// hadn't been set yet). `allowed_labels` requires ≥ 1 so the classifier has
+// something to match against.
+//
+// `timeout_ms` is bounded (1..600_000): the upper bound matches Node's
+// setTimeout int32 sanity range and prevents pathological YAML like
+// `timeout_ms: 9999999999999`. The lower bound stops a "0 ms" misconfiguration
+// from looking like "no timeout" to the strategy (which defaults to 30 s).
+// ---------------------------------------------------------------------------
+const SubagentCallArgs = z.object({
+    model: z.string().min(1),
+    prompt: z.string().min(1),
+    timeout_ms: z.number().int().positive().max(600_000).optional(),
+});
+const LlmClassifyArgs = z.object({
+    model: z.string().min(1),
+    prompt: z.string().min(1),
+    allowed_labels: z.array(z.string().min(1)).min(1),
+    timeout_ms: z.number().int().positive().max(600_000).optional(),
+});
+export function registerLlmFunctions(registry) {
+    // DURABLE.2 — both primitives in this file dispatch through a model
+    // strategy (subprocess CLI or HTTP-API client). Either path is slow + has
+    // a token cost, so we ALWAYS checkpoint: re-running on resume would
+    // double-charge the user's subscription / API quota. `subagent_call` is
+    // `memoizable: false` because its outputs are non-deterministic (model
+    // temperature, narrative generation); `llm_classify` IS memoizable because
+    // the pack-supplied `allowed_labels` clamps the output space and the
+    // classifier prompt is intentionally low-temp.
+    registry.register({
+        name: 'subagent_call',
+        argSchema: SubagentCallArgs,
+        durable: true,
+        memoizable: false,
+        costEstimateMs: 30_000,
+        execute: async ({ model, prompt, timeout_ms }, ctx) => {
+            // PR-followup: thread pack-shipped `models.yaml` through the resolver
+            // so a pack's declared alias works out of the box without a user-level
+            // `~/.opensquid/models.yaml`. `ctx.packModels` is `undefined` for
+            // packs that ship no `models.yaml` and for legacy non-pack call sites.
+            const cfg = await loadModelsConfig(ctx.packModels);
+            const aliasCfg = cfg[model];
+            if (!aliasCfg) {
+                return err({
+                    kind: 'arg_invalid',
+                    message: `Unknown model alias "${model}"`,
+                });
+            }
+            try {
+                const strategy = resolveStrategy(model, aliasCfg);
+                // Pass timeout only when defined — exactOptionalPropertyTypes
+                // forbids forwarding `undefined` into an optional slot.
+                const out = timeout_ms === undefined
+                    ? await strategy.call(prompt)
+                    : await strategy.call(prompt, { timeoutMs: timeout_ms });
+                return ok(out);
+            }
+            catch (e) {
+                return err({
+                    kind: 'runtime',
+                    message: `subagent_call(${model}): ${String(e)}`,
+                    cause: e,
+                });
+            }
+        },
+    });
+    registry.register({
+        name: 'llm_classify',
+        argSchema: LlmClassifyArgs,
+        durable: true,
+        memoizable: true,
+        costEstimateMs: 3000,
+        execute: async ({ model, prompt, allowed_labels, timeout_ms }, ctx) => {
+            // PR-followup: same `ctx.packModels` thread-through as `subagent_call`.
+            const cfg = await loadModelsConfig(ctx.packModels);
+            const aliasCfg = cfg[model];
+            if (!aliasCfg) {
+                return err({
+                    kind: 'arg_invalid',
+                    message: `Unknown model alias "${model}"`,
+                });
+            }
+            // Prompt-engineering note: " | " separator + explicit "No other words"
+            // suffix is the lowest-temp shape we found that works across both
+            // subscription-CLI hosts and direct-API mid-size models. Don't change
+            // this without re-validating against the classifier eval set.
+            const wrappedPrompt = `${prompt}\n\nRespond with exactly one of: ${allowed_labels.join(' | ')}.\nNo other words.`;
+            try {
+                const strategy = resolveStrategy(model, aliasCfg);
+                const raw = timeout_ms === undefined
+                    ? await strategy.call(wrappedPrompt)
+                    : await strategy.call(wrappedPrompt, { timeoutMs: timeout_ms });
+                // First whitespace-delimited token of the trimmed output. Some
+                // models append a trailing "." or chatter despite "No other words";
+                // we keep only the first token so "ONE_LOGICAL_UNIT." still matches
+                // "ONE_LOGICAL_UNIT" (after a final character-class strip below
+                // could be added in Phase 2 if eval data warrants it).
+                const trimmed = raw.trim();
+                const firstToken = trimmed.split(/\s+/)[0] ?? '';
+                const match = allowed_labels.find((l) => l === firstToken || l.toLowerCase() === firstToken.toLowerCase());
+                return ok(match ?? 'UNCERTAIN');
+            }
+            catch {
+                // Clamp every classifier failure to UNCERTAIN. See header comment
+                // for the rationale and the audit knob ("UNCERTAIN rate").
+                return ok('UNCERTAIN');
+            }
+        },
+    });
+}
+//# sourceMappingURL=llm.js.map

package/dist/functions/llm.js.map

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

package/dist/functions/path_exists.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `path_exists` primitive — read-only check for files matching a basename
+ * glob within a single directory, resolved relative to the event cwd.
+ *
+ * Powers the `scope-decomposer` skill's hard gate (Track SD): "a task/track
+ * spec is being written but no `docs/research/*-pre-research-*.md` artifact
+ * exists yet". Single-directory, non-recursive, NO glob dependency — it uses
+ * `node:fs/promises.readdir` + a basename glob→RegExp match, because opensquid
+ * pins Node `>=20` (where `fs.glob` is not stable) and ships no glob library.
+ * Avoiding a new dep also keeps the license surface clean.
+ *
+ * Capability floor: `dir` resolves against the event cwd and MUST stay inside
+ * that subtree — absolute dirs and `..` escapes are rejected with
+ * `arg_invalid`. The primitive never writes, never shells out, and never reads
+ * file CONTENTS (only directory entry names).
+ *
+ * Error model: `arg_invalid` on absolute/escaping `dir`. A missing directory
+ * is NOT an error — it returns `ok({ exists: false, matches: [] })`, because
+ * the gate must treat an absent `docs/research/` as "no artifact". Never throws.
+ *
+ * `memoizable: false` is load-bearing: disk truth changes within a session
+ * (the agent creates the artifact, then the gate must see it), so a memoized
+ * result would report a stale "missing" and defeat the relax-after-compliance
+ * path.
+ *
+ * Imports from: node:fs/promises, node:path, zod, ../runtime/result.js.
+ * Imported by: src/runtime/bootstrap.ts (registry wiring).
+ */
+import { z } from 'zod';
+import type { FunctionDef } from './registry.js';
+export declare const PathExistsArgs: z.ZodObject<{
+    /** Directory to scan, relative to the resolved base. Absolute / escaping rejected. */
+    dir: z.ZodString;
+    /** Basename glob: `*` (any run) and `?` (single char). Matched against entry names. */
+    pattern: z.ZodString;
+    /**
+     * Optional anchor: when set, resolve `dir` against the GIT REPO ROOT of this
+     * file (walk up from its dirname to the nearest `.git`), NOT the event cwd.
+     * Fixes the cross-repo false-block: a spec written in the planning repo
+     * resolves its sibling `docs/research` correctly even when the working cwd
+     * is a different (code) repo. Write/Edit always pass an absolute file_path,
+     * so the anchor is reliable; falls back to cwd if no repo root is found.
+     */
+    base_file: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    pattern: string;
+    dir: string;
+    base_file?: string | undefined;
+}, {
+    pattern: string;
+    dir: string;
+    base_file?: string | undefined;
+}>;
+interface PathExistsResult {
+    exists: boolean;
+    matches: string[];
+}
+export declare const PathExists: FunctionDef<z.input<typeof PathExistsArgs>, PathExistsResult>;
+export {};
+//# sourceMappingURL=path_exists.d.ts.map

package/dist/functions/path_exists.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path_exists.d.ts","sourceRoot":"","sources":["../../src/functions/path_exists.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,eAAO,MAAM,cAAc;IAEvB,sFAAsF;;IAEtF,uFAAuF;;IAEvF;;;;;;;OAOG;;;;;;;;;;EAGI,CAAC;AAkBZ,UAAU,gBAAgB;IACxB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAgBD,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,EAAE,gBAAgB,CA+CpF,CAAC"}

package/dist/functions/path_exists.js

@@ -0,0 +1,129 @@
+/**
+ * `path_exists` primitive — read-only check for files matching a basename
+ * glob within a single directory, resolved relative to the event cwd.
+ *
+ * Powers the `scope-decomposer` skill's hard gate (Track SD): "a task/track
+ * spec is being written but no `docs/research/*-pre-research-*.md` artifact
+ * exists yet". Single-directory, non-recursive, NO glob dependency — it uses
+ * `node:fs/promises.readdir` + a basename glob→RegExp match, because opensquid
+ * pins Node `>=20` (where `fs.glob` is not stable) and ships no glob library.
+ * Avoiding a new dep also keeps the license surface clean.
+ *
+ * Capability floor: `dir` resolves against the event cwd and MUST stay inside
+ * that subtree — absolute dirs and `..` escapes are rejected with
+ * `arg_invalid`. The primitive never writes, never shells out, and never reads
+ * file CONTENTS (only directory entry names).
+ *
+ * Error model: `arg_invalid` on absolute/escaping `dir`. A missing directory
+ * is NOT an error — it returns `ok({ exists: false, matches: [] })`, because
+ * the gate must treat an absent `docs/research/` as "no artifact". Never throws.
+ *
+ * `memoizable: false` is load-bearing: disk truth changes within a session
+ * (the agent creates the artifact, then the gate must see it), so a memoized
+ * result would report a stale "missing" and defeat the relax-after-compliance
+ * path.
+ *
+ * Imports from: node:fs/promises, node:path, zod, ../runtime/result.js.
+ * Imported by: src/runtime/bootstrap.ts (registry wiring).
+ */
+import { readdir, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { z } from 'zod';
+import { err, ok } from '../runtime/result.js';
+export const PathExistsArgs = z
+    .object({
+    /** Directory to scan, relative to the resolved base. Absolute / escaping rejected. */
+    dir: z.string().min(1),
+    /** Basename glob: `*` (any run) and `?` (single char). Matched against entry names. */
+    pattern: z.string().min(1),
+    /**
+     * Optional anchor: when set, resolve `dir` against the GIT REPO ROOT of this
+     * file (walk up from its dirname to the nearest `.git`), NOT the event cwd.
+     * Fixes the cross-repo false-block: a spec written in the planning repo
+     * resolves its sibling `docs/research` correctly even when the working cwd
+     * is a different (code) repo. Write/Edit always pass an absolute file_path,
+     * so the anchor is reliable; falls back to cwd if no repo root is found.
+     */
+    base_file: z.string().min(1).optional(),
+})
+    .strict();
+/** Walk up from `start` to the nearest dir containing `.git`; null at fs root. */
+async function repoRootOf(start) {
+    let dir = start;
+    for (;;) {
+        try {
+            await stat(join(dir, '.git'));
+            return dir;
+        }
+        catch {
+            /* keep walking up */
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Compile a basename glob (`*`, `?`) to an anchored RegExp. All other regex
+ * metacharacters are escaped first, so the only wildcards are the two glob
+ * tokens. Patterns are first-party (pack YAML), single-segment, and anchored —
+ * no catastrophic-backtracking surface.
+ */
+function globToRegExp(pattern) {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '.*')
+        .replace(/\?/g, '.');
+    return new RegExp(`^${escaped}$`);
+}
+export const PathExists = {
+    name: 'path_exists',
+    argSchema: PathExistsArgs,
+    durable: false,
+    memoizable: false,
+    costEstimateMs: 5,
+    execute: async (args, ctx) => {
+        if (isAbsolute(args.dir)) {
+            return err({
+                kind: 'arg_invalid',
+                message: `path_exists: absolute dir not allowed ("${args.dir}")`,
+            });
+        }
+        const cwd = ctx.event.kind === 'tool_call' ? (ctx.event.cwd ?? process.cwd()) : process.cwd();
+        // base_file anchors to the file's repo root (cwd-independent) — fixes the
+        // cross-repo false-block where a planning-repo spec is edited from a code
+        // repo's cwd and its sibling docs/research can't be found.
+        let base = cwd;
+        if (args.base_file !== undefined && args.base_file !== '') {
+            const fileAbs = isAbsolute(args.base_file) ? args.base_file : resolve(cwd, args.base_file);
+            base = (await repoRootOf(dirname(fileAbs))) ?? cwd;
+        }
+        const target = resolve(base, args.dir);
+        const rel = relative(base, target);
+        if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+            return err({
+                kind: 'arg_invalid',
+                message: `path_exists: dir escapes cwd subtree ("${args.dir}")`,
+            });
+        }
+        const re = globToRegExp(args.pattern);
+        let entries;
+        try {
+            entries = await readdir(target);
+        }
+        catch (e) {
+            if (e.code === 'ENOENT') {
+                return ok({ exists: false, matches: [] });
+            }
+            return err({
+                kind: 'runtime',
+                message: `path_exists: readdir failed for "${args.dir}": ${e.message}`,
+                cause: e,
+            });
+        }
+        const matches = entries.filter((name) => re.test(name)).sort();
+        return ok({ exists: matches.length > 0, matches });
+    },
+};
+//# sourceMappingURL=path_exists.js.map