opensquid 0.5.395

package/dist/functions/effective_content.js.map

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

package/dist/functions/ensure_umbrella_topic.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `ensure_umbrella_topic` primitive (T-CHAT-AS-TERMINAL CAT.7 — SessionStart
+ * topic assurance, umbrella-level ≤1 topic).
+ *
+ * The SECOND consumer of the SessionStart hook mechanism (HH6.1) and the FIRST
+ * one sanctioned to take an ACTION on `session_start`. Where
+ * `check_chat_connection` is REPORT-ONLY, CAT.7 — under the remote-terminal
+ * override [[project_opensquid_chat_is_remote_terminal]] — guarantees the
+ * session's UMBRELLA owns exactly one telegram forum topic so inbound/outbound
+ * chat lands in an isolated thread.
+ *
+ * The assurance, on `session_start`:
+ *
+ *   1. Resolve cwd → umbrella via `loadChannelsConfig` + `resolveUmbrellaForCwd`.
+ *      - cwd in NO umbrella  → NO-OP. We never fabricate an umbrella row; that
+ *        is the setup wizard's job. The session simply has no chat binding.
+ *   2. Inspect the resolved umbrella's `telegram` binding:
+ *      - already has a `topic_id`  → NO-OP (use the existing one topic). This is
+ *        the umbrella-level ≤1:1 invariant in action: an opensquid-cwd session
+ *        and a loop-cwd session both resolve to the SAME loop umbrella row, so
+ *        the second session sees `topic_id` already set and NEVER creates a 2nd.
+ *      - no `telegram` binding at all (no `chat_id`)  → NO-OP. Nothing to attach
+ *        a topic to; the wizard hasn't wired the supergroup yet.
+ *      - has `chat_id` but NO `topic_id`  → the ZERO-topic case: proceed.
+ *   3. Gate on the chat-daemon being LIVE (a `ping` over its socket). No daemon
+ *      → NO-OP. The assurance only runs when chat is live (a live remote
+ *      terminal); we never spawn the daemon here.
+ *   4. Create EXACTLY ONE topic via the daemon `create_topic` RPC
+ *      ({platform:'telegram', chat_id, name} → {message_thread_id, name}), with
+ *      an umbrella-derived name, then write `topic_id` back into THAT umbrella's
+ *      row in `channels.json` via an atomic write that preserves every other
+ *      field/row. Once `topic_id` is set, step 2 makes every subsequent run a
+ *      no-op — idempotent, ≤1 topic per umbrella by construction.
+ *
+ * Fail-quiet: every failure mode (no daemon, RPC error, IO error, malformed
+ * config) returns `ok(null)` and NEVER blocks session start. CAT.7 emits no
+ * inject_context — it is a pure side-effecting assurance, so `null` (the
+ * no-verdict branch) is the only return.
+ *
+ * Seams (test injection, no socket / no Telegram in unit tests):
+ *   - `createTopic`  — the daemon `create_topic` RPC dial. Default dials the
+ *     daemon socket one-shot (mirrors `chat_send.ts defaultDaemonSend`).
+ *   - `daemonRunning` — the live-daemon gate. Default `ping`s the socket.
+ *   - `now`          — clock (unused today; reserved for name stamping).
+ *
+ * Imports from: zod, node:net, node:os, node:path, ../channels/routing.js,
+ *   ../runtime/atomic_write.js, ../runtime/result.js.
+ * Imported by: src/runtime/bootstrap.ts (registry wiring).
+ */
+import type { FunctionRegistry } from './registry.js';
+/** The daemon `create_topic` RPC: chat_id + name → the new thread id. */
+export type CreateTopicFn = (args: {
+    chatId: string;
+    name: string;
+}) => Promise<{
+    message_thread_id: number;
+    name: string;
+}>;
+/** The live-daemon gate: true iff a chat-daemon answers on its socket. */
+export type DaemonRunningFn = () => Promise<boolean>;
+export interface EnsureUmbrellaTopicDeps {
+    createTopic?: CreateTopicFn;
+    daemonRunning?: DaemonRunningFn;
+}
+export declare function registerEnsureUmbrellaTopicFunction(registry: FunctionRegistry, deps?: EnsureUmbrellaTopicDeps): void;
+//# sourceMappingURL=ensure_umbrella_topic.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ensure_umbrella_topic.d.ts","sourceRoot":"","sources":["../../src/functions/ensure_umbrella_topic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAgBH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAMtD,yEAAyE;AACzE,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd,KAAK,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE3D,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;AAErD,MAAM,WAAW,uBAAuB;IACtC,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,aAAa,CAAC,EAAE,eAAe,CAAC;CACjC;AAuDD,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,GAAE,uBAA4B,GACjC,IAAI,CAgDN"}

package/dist/functions/ensure_umbrella_topic.js

@@ -0,0 +1,148 @@
+/**
+ * `ensure_umbrella_topic` primitive (T-CHAT-AS-TERMINAL CAT.7 — SessionStart
+ * topic assurance, umbrella-level ≤1 topic).
+ *
+ * The SECOND consumer of the SessionStart hook mechanism (HH6.1) and the FIRST
+ * one sanctioned to take an ACTION on `session_start`. Where
+ * `check_chat_connection` is REPORT-ONLY, CAT.7 — under the remote-terminal
+ * override [[project_opensquid_chat_is_remote_terminal]] — guarantees the
+ * session's UMBRELLA owns exactly one telegram forum topic so inbound/outbound
+ * chat lands in an isolated thread.
+ *
+ * The assurance, on `session_start`:
+ *
+ *   1. Resolve cwd → umbrella via `loadChannelsConfig` + `resolveUmbrellaForCwd`.
+ *      - cwd in NO umbrella  → NO-OP. We never fabricate an umbrella row; that
+ *        is the setup wizard's job. The session simply has no chat binding.
+ *   2. Inspect the resolved umbrella's `telegram` binding:
+ *      - already has a `topic_id`  → NO-OP (use the existing one topic). This is
+ *        the umbrella-level ≤1:1 invariant in action: an opensquid-cwd session
+ *        and a loop-cwd session both resolve to the SAME loop umbrella row, so
+ *        the second session sees `topic_id` already set and NEVER creates a 2nd.
+ *      - no `telegram` binding at all (no `chat_id`)  → NO-OP. Nothing to attach
+ *        a topic to; the wizard hasn't wired the supergroup yet.
+ *      - has `chat_id` but NO `topic_id`  → the ZERO-topic case: proceed.
+ *   3. Gate on the chat-daemon being LIVE (a `ping` over its socket). No daemon
+ *      → NO-OP. The assurance only runs when chat is live (a live remote
+ *      terminal); we never spawn the daemon here.
+ *   4. Create EXACTLY ONE topic via the daemon `create_topic` RPC
+ *      ({platform:'telegram', chat_id, name} → {message_thread_id, name}), with
+ *      an umbrella-derived name, then write `topic_id` back into THAT umbrella's
+ *      row in `channels.json` via an atomic write that preserves every other
+ *      field/row. Once `topic_id` is set, step 2 makes every subsequent run a
+ *      no-op — idempotent, ≤1 topic per umbrella by construction.
+ *
+ * Fail-quiet: every failure mode (no daemon, RPC error, IO error, malformed
+ * config) returns `ok(null)` and NEVER blocks session start. CAT.7 emits no
+ * inject_context — it is a pure side-effecting assurance, so `null` (the
+ * no-verdict branch) is the only return.
+ *
+ * Seams (test injection, no socket / no Telegram in unit tests):
+ *   - `createTopic`  — the daemon `create_topic` RPC dial. Default dials the
+ *     daemon socket one-shot (mirrors `chat_send.ts defaultDaemonSend`).
+ *   - `daemonRunning` — the live-daemon gate. Default `ping`s the socket.
+ *   - `now`          — clock (unused today; reserved for name stamping).
+ *
+ * Imports from: zod, node:net, node:os, node:path, ../channels/routing.js,
+ *   ../runtime/atomic_write.js, ../runtime/result.js.
+ * Imported by: src/runtime/bootstrap.ts (registry wiring).
+ */
+import { readFile } from 'node:fs/promises';
+import { z } from 'zod';
+import { channelsConfigPath, loadChannelsConfig, resolveUmbrellaForCwd, } from '../channels/routing.js';
+import { createTopic as clientCreateTopic, pingDaemon } from '../chat_daemon/client.js';
+import { atomicWriteFile } from '../runtime/atomic_write.js';
+import { ok } from '../runtime/result.js';
+// ---------------------------------------------------------------------------
+// Default seams — the shared chat-daemon client (src/chat_daemon/client.ts).
+// CL.3 (T-CHAT-FINALIZE-REMOVE-LEGACY): this module previously carried its OWN
+// copy of the socket dance (daemonSocketPath + daemonRpc) — the 5th copy the
+// audit found. Both now delegate to the one owner.
+// ---------------------------------------------------------------------------
+/** Default `create_topic` dial — the shared client's one-shot RPC. */
+const defaultCreateTopic = (args) => clientCreateTopic(args.chatId, args.name);
+/** Default daemon-running gate — the shared client's `ping`. */
+const defaultDaemonRunning = () => pingDaemon();
+// ---------------------------------------------------------------------------
+// Umbrella-derived topic name. Keep it short + stable + human-scannable.
+// ---------------------------------------------------------------------------
+function topicNameForUmbrella(umbrellaId) {
+    return `opensquid: ${umbrellaId}`;
+}
+// ---------------------------------------------------------------------------
+// channels.json write-back — set the resolved umbrella's `topic_id`, preserve
+// every other field and row, atomic publish. Re-reads the freshest config off
+// disk just before the write (not the snapshot the resolver saw) so a
+// concurrent edit to a SIBLING row is not clobbered.
+// ---------------------------------------------------------------------------
+async function writeBackTopicId(umbrellaId, topicId) {
+    // Re-read raw to preserve any keys the (strict) schema would round-trip
+    // identically; we mutate only the one umbrella's telegram.topic_id.
+    const raw = await readFile(channelsConfigPath(), 'utf8');
+    const cfg = JSON.parse(raw);
+    const row = cfg.umbrellas.find((u) => u.id === umbrellaId);
+    if (row?.telegram === undefined) {
+        // The row/binding vanished between resolve and write — abort the write-back
+        // rather than fabricate state. Caller is fail-quiet.
+        throw new Error(`umbrella ${umbrellaId} no longer has a telegram binding`);
+    }
+    // Idempotency belt-and-suspenders: never overwrite an existing topic_id.
+    if (row.telegram.topic_id !== undefined)
+        return;
+    row.telegram.topic_id = topicId;
+    await atomicWriteFile(channelsConfigPath(), JSON.stringify(cfg, null, 2) + '\n');
+}
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+// `cwd` is an optional override (tests inject it); production reads it from the
+// session_start event payload via ctx.
+const EnsureUmbrellaTopicArgs = z.object({ cwd: z.string().optional() }).strict();
+export function registerEnsureUmbrellaTopicFunction(registry, deps = {}) {
+    const createTopic = deps.createTopic ?? defaultCreateTopic;
+    const daemonRunning = deps.daemonRunning ?? defaultDaemonRunning;
+    registry.register({
+        name: 'ensure_umbrella_topic',
+        argSchema: EnsureUmbrellaTopicArgs,
+        durable: false,
+        memoizable: false,
+        costEstimateMs: 40,
+        execute: async (args, ctx) => {
+            try {
+                const cwd = args.cwd ??
+                    (ctx.event.kind === 'session_start' ? ctx.event.cwd : undefined) ??
+                    process.cwd();
+                // 1. cwd → umbrella. Absent config / unresolved cwd → no-op.
+                const channels = await loadChannelsConfig();
+                if (channels === null)
+                    return ok(null);
+                const umbrellaId = resolveUmbrellaForCwd(channels, cwd);
+                if (umbrellaId === null)
+                    return ok(null);
+                const row = channels.umbrellas.find((u) => u.id === umbrellaId);
+                if (row?.telegram === undefined)
+                    return ok(null); // no binding → wizard's job
+                // 2. Already has its one topic → no-op (≤1:1 invariant). This is also
+                // the "second cwd in the same umbrella" path: the first session set
+                // topic_id, the second sees it and never creates a 2nd.
+                if (row.telegram.topic_id !== undefined)
+                    return ok(null);
+                // 3. Zero-topic case. Gate on the daemon being live; no daemon → no-op.
+                if (!(await daemonRunning()))
+                    return ok(null);
+                // 4. Create EXACTLY ONE topic, then write topic_id back atomically.
+                const created = await createTopic({
+                    chatId: row.telegram.chat_id,
+                    name: topicNameForUmbrella(umbrellaId),
+                });
+                await writeBackTopicId(umbrellaId, created.message_thread_id);
+                return ok(null);
+            }
+            catch {
+                // Fail-quiet: the assurance must never break session start.
+                return ok(null);
+            }
+        },
+    });
+}
+//# sourceMappingURL=ensure_umbrella_topic.js.map

package/dist/functions/ensure_umbrella_topic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure_umbrella_topic.js","sourceRoot":"","sources":["../../src/functions/ensure_umbrella_topic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,GAEtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,WAAW,IAAI,iBAAiB,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACxF,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,EAAE,EAAE,MAAM,sBAAsB,CAAC;AAsB1C,8EAA8E;AAC9E,6EAA6E;AAC7E,+EAA+E;AAC/E,6EAA6E;AAC7E,mDAAmD;AACnD,8EAA8E;AAE9E,sEAAsE;AACtE,MAAM,kBAAkB,GAAkB,CAAC,IAAI,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;AAE9F,gEAAgE;AAChE,MAAM,oBAAoB,GAAoB,GAAG,EAAE,CAAC,UAAU,EAAE,CAAC;AAEjE,8EAA8E;AAC9E,yEAAyE;AACzE,8EAA8E;AAE9E,SAAS,oBAAoB,CAAC,UAAkB;IAC9C,OAAO,cAAc,UAAU,EAAE,CAAC;AACpC,CAAC;AAED,8EAA8E;AAC9E,8EAA8E;AAC9E,8EAA8E;AAC9E,sEAAsE;AACtE,qDAAqD;AACrD,8EAA8E;AAE9E,KAAK,UAAU,gBAAgB,CAAC,UAAkB,EAAE,OAAe;IACjE,wEAAwE;IACxE,oEAAoE;IACpE,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,kBAAkB,EAAE,EAAE,MAAM,CAAC,CAAC;IACzD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAmB,CAAC;IAC9C,MAAM,GAAG,GAAG,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,UAAU,CAAC,CAAC;IAC3D,IAAI,GAAG,EAAE,QAAQ,KAAK,SAAS,EAAE,CAAC;QAChC,4EAA4E;QAC5E,qDAAqD;QACrD,MAAM,IAAI,KAAK,CAAC,YAAY,UAAU,mCAAmC,CAAC,CAAC;IAC7E,CAAC;IACD,yEAAyE;IACzE,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO;IAChD,GAAG,CAAC,QAAQ,CAAC,QAAQ,GAAG,OAAO,CAAC;IAChC,MAAM,eAAe,CAAC,kBAAkB,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AACnF,CAAC;AAED,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E,gFAAgF;AAChF,uCAAuC;AACvC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AAElF,MAAM,UAAU,mCAAmC,CACjD,QAA0B,EAC1B,OAAgC,EAAE;IAElC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,kBAAkB,CAAC;IAC3D,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,oBAAoB,CAAC;IAEjE,QAAQ,CAAC,QAAQ,CAAC;QAChB,IAAI,EAAE,uBAAuB;QAC7B,SAAS,EAAE,uBAAuB;QAClC,OAAO,EAAE,KAAK;QACd,UAAU,EAAE,KAAK;QACjB,cAAc,EAAE,EAAE;QAClB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;YAC3B,IAAI,CAAC;gBACH,MAAM,GAAG,GACP,IAAI,CAAC,GAAG;oBACR,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;oBAChE,OAAO,CAAC,GAAG,EAAE,CAAC;gBAEhB,6DAA6D;gBAC7D,MAAM,QAAQ,GAAG,MAAM,kBAAkB,EAAE,CAAC;gBAC5C,IAAI,QAAQ,KAAK,IAAI;oBAAE,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;gBACvC,MAAM,UAAU,GAAG,qBAAqB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;gBACxD,IAAI,UAAU,KAAK,IAAI;oBAAE,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;gBAEzC,MAAM,GAAG,GAAG,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,UAAU,CAAC,CAAC;gBAChE,IAAI,GAAG,EAAE,QAAQ,KAAK,SAAS;oBAAE,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,4BAA4B;gBAE9E,sEAAsE;gBACtE,oEAAoE;gBACpE,wDAAwD;gBACxD,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,KAAK,SAAS;oBAAE,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;gBAEzD,wEAAwE;gBACxE,IAAI,CAAC,CAAC,MAAM,aAAa,EAAE,CAAC;oBAAE,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;gBAE9C,oEAAoE;gBACpE,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC;oBAChC,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAC,OAAO;oBAC5B,IAAI,EAAE,oBAAoB,CAAC,UAAU,CAAC;iBACvC,CAAC,CAAC;gBACH,MAAM,gBAAgB,CAAC,UAAU,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;gBAE9D,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;YAClB,CAAC;YAAC,MAAM,CAAC;gBACP,4DAA4D;gBAC5D,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;YAClB,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/functions/event.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Event-inspection primitives: `tool_name`, `tool_args`, `cwd`,
+ * `last_assistant_message`, `match_command`.
+ *
+ * Note on `require-await`: the `FunctionDef.execute` contract is
+ * `Promise<Result<...>>`. These five primitives are pure reads off
+ * `EvalCtx.event` — no awaitable work to do. We satisfy the contract by
+ * declaring the methods `async` (which wraps the return value in a Promise)
+ * and disable `@typescript-eslint/require-await` for this file. Future
+ * primitives in this file should keep the file-level disable as-is.
+ *
+ * Per `docs/opensquid-real-design.md` §"Phase 1 — Runtime skeleton" (event
+ * inspection primitives). These five primitives are the read-only accessors
+ * skills compose to interrogate the current `Event` carried in `EvalCtx`.
+ *
+ * Wrong-kind discipline: every accessor returns `ok(null)` (or `ok(false)`
+ * for `match_command`) when the event kind doesn't match what the accessor
+ * expects. NEVER throws, NEVER errs — wrong-kind is a normal control-flow
+ * signal that skills branch on, not a failure. The evaluator's stray-throw
+ * wrapper is reserved for genuine bugs.
+ *
+ * `match_command` shallow-path contract: `target` is `tool_args.<field>` and
+ * resolves only one level deep. Nested paths (e.g. `tool_args.input.text`)
+ * are out of scope for Phase 1 — skills can pre-stage a deeper field via a
+ * future accessor primitive. Bad regex returns `err({ kind: 'arg_invalid' })`
+ * rather than throwing so the evaluator's per-step error path picks it up
+ * cleanly.
+ *
+ * Imports from: zod, ../runtime/result.js, ./registry.js.
+ * Imported by: src/functions/index.ts (registry wiring).
+ */
+import type { FunctionRegistry } from './registry.js';
+export declare function registerEventFunctions(registry: FunctionRegistry): void;
+//# sourceMappingURL=event.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../src/functions/event.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAkCtD,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAmGvE"}

package/dist/functions/event.js

@@ -0,0 +1,164 @@
+/* eslint-disable @typescript-eslint/require-await */
+/**
+ * Event-inspection primitives: `tool_name`, `tool_args`, `cwd`,
+ * `last_assistant_message`, `match_command`.
+ *
+ * Note on `require-await`: the `FunctionDef.execute` contract is
+ * `Promise<Result<...>>`. These five primitives are pure reads off
+ * `EvalCtx.event` — no awaitable work to do. We satisfy the contract by
+ * declaring the methods `async` (which wraps the return value in a Promise)
+ * and disable `@typescript-eslint/require-await` for this file. Future
+ * primitives in this file should keep the file-level disable as-is.
+ *
+ * Per `docs/opensquid-real-design.md` §"Phase 1 — Runtime skeleton" (event
+ * inspection primitives). These five primitives are the read-only accessors
+ * skills compose to interrogate the current `Event` carried in `EvalCtx`.
+ *
+ * Wrong-kind discipline: every accessor returns `ok(null)` (or `ok(false)`
+ * for `match_command`) when the event kind doesn't match what the accessor
+ * expects. NEVER throws, NEVER errs — wrong-kind is a normal control-flow
+ * signal that skills branch on, not a failure. The evaluator's stray-throw
+ * wrapper is reserved for genuine bugs.
+ *
+ * `match_command` shallow-path contract: `target` is `tool_args.<field>` and
+ * resolves only one level deep. Nested paths (e.g. `tool_args.input.text`)
+ * are out of scope for Phase 1 — skills can pre-stage a deeper field via a
+ * future accessor primitive. Bad regex returns `err({ kind: 'arg_invalid' })`
+ * rather than throwing so the evaluator's per-step error path picks it up
+ * cleanly.
+ *
+ * Imports from: zod, ../runtime/result.js, ./registry.js.
+ * Imported by: src/functions/index.ts (registry wiring).
+ */
+import { z } from 'zod';
+import { err, ok } from '../runtime/result.js';
+// ---------------------------------------------------------------------------
+// Zod arg schemas — `.strict()` on EmptyArgs so unexpected keys become
+// `arg_invalid` at registry-call time (better than silently ignoring typos
+// in YAML). `MatchCommandArgs` keeps `target` optional; default behavior
+// reads `tool_args.command`.
+// ---------------------------------------------------------------------------
+const EmptyArgs = z.object({}).strict();
+const MatchCommandArgs = z.object({
+    pattern: z.string(),
+    target: z.string().optional(),
+});
+// ---------------------------------------------------------------------------
+// resolveCommandField — shallow `tool_args.<field>` lookup for match_command.
+//
+// `target` undefined or exactly `tool_args.command` → read `args.command`.
+// Anything else with a `tool_args.` prefix → read `args[<rest>]`. Missing
+// field or non-string value → empty string (regex tests against `''`, which
+// for any non-trivial pattern is `false` — matches the "no command, no
+// match" intuition).
+// ---------------------------------------------------------------------------
+function resolveCommandField(args, target) {
+    const field = target === undefined || target === 'tool_args.command'
+        ? 'command'
+        : target.replace(/^tool_args\./, '');
+    const value = args[field];
+    return typeof value === 'string' ? value : '';
+}
+export function registerEventFunctions(registry) {
+    // DURABLE.2 — every primitive in this file is a pure read off `EvalCtx.event`
+    // (no I/O, no LLM call). Cost is sub-microsecond; checkpoint overhead would
+    // exceed re-run cost by orders of magnitude. `match_command` runs one regex
+    // — still cheap; `costEstimateMs: 0.1` is the order-of-magnitude marker the
+    // benchmarks use to group "trivial" primitives.
+    registry.register({
+        name: 'tool_name',
+        argSchema: EmptyArgs,
+        durable: false,
+        memoizable: false,
+        costEstimateMs: 0.1,
+        execute: async (_args, ctx) => {
+            // Both tool_call (PreToolUse) and post_tool_call (PostToolUse) carry the
+            // tool name; a rule on either event can read it. Any other event → null.
+            if (ctx.event.kind === 'tool_call' || ctx.event.kind === 'post_tool_call') {
+                return ok(ctx.event.tool);
+            }
+            return ok(null);
+        },
+    });
+    registry.register({
+        name: 'tool_args',
+        argSchema: EmptyArgs,
+        durable: false,
+        memoizable: false,
+        costEstimateMs: 0.1,
+        execute: async (_args, ctx) => {
+            if (ctx.event.kind !== 'tool_call')
+                return ok(null);
+            return ok(ctx.event.args);
+        },
+    });
+    registry.register({
+        name: 'cwd',
+        argSchema: EmptyArgs,
+        durable: false,
+        memoizable: false,
+        costEstimateMs: 0.1,
+        execute: async (_args, ctx) => {
+            if (ctx.event.kind !== 'tool_call')
+                return ok(null);
+            return ok(ctx.event.cwd ?? null);
+        },
+    });
+    registry.register({
+        name: 'last_assistant_message',
+        argSchema: EmptyArgs,
+        durable: false,
+        memoizable: false,
+        costEstimateMs: 0.1,
+        execute: async (_args, ctx) => {
+            // RJ.1: the prior assistant turn is available at BOTH stop (current
+            // turn, but off-by-one-prone) and prompt_submit (the SETTLED prior turn,
+            // filled by the UPS hook from the transcript — no off-by-one). Every
+            // other event kind has no assistant text → null.
+            if (ctx.event.kind === 'stop')
+                return ok(ctx.event.assistantText);
+            if (ctx.event.kind === 'prompt_submit')
+                return ok(ctx.event.priorAssistantText ?? null);
+            return ok(null);
+        },
+    });
+    registry.register({
+        name: 'recent_turns',
+        argSchema: EmptyArgs,
+        durable: false,
+        memoizable: false,
+        costEstimateMs: 0.1,
+        execute: async (_args, ctx) => {
+            // FU.2: the last N conversation turns (role-labeled), filled by the UPS
+            // hook from the transcript. Only present on prompt_submit; null elsewhere.
+            if (ctx.event.kind === 'prompt_submit')
+                return ok(ctx.event.recentTurns ?? null);
+            return ok(null);
+        },
+    });
+    registry.register({
+        name: 'match_command',
+        argSchema: MatchCommandArgs,
+        durable: false,
+        memoizable: false,
+        costEstimateMs: 0.1,
+        execute: async ({ pattern, target }, ctx) => {
+            if (ctx.event.kind !== 'tool_call')
+                return ok(false);
+            const command = resolveCommandField(ctx.event.args, target);
+            let regex;
+            try {
+                regex = new RegExp(pattern);
+            }
+            catch (e) {
+                return err({
+                    kind: 'arg_invalid',
+                    message: `Bad regex for match_command: ${pattern}`,
+                    cause: e,
+                });
+            }
+            return ok(regex.test(command));
+        },
+    });
+}
+//# sourceMappingURL=event.js.map

package/dist/functions/event.js.map

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

package/dist/functions/file_write.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `file_write` primitive — gated arbitrary-path file writer (AUTO.3).
+ *
+ * Distinct from `write_state` (in `./state.ts`), which writes ONLY into
+ * `~/.opensquid/sessions/<id>/state/` or `~/.opensquid/packs/<id>/state/`.
+ * `file_write` is the primitive that handles user-content writes (skill
+ * outputs, generated reports, ingest results) and so must pass through
+ * the capability gate.
+ *
+ * Atomicity: tmp-file + rename, same idiom as `state.atomicWriteJson`.
+ *
+ * Gate posture: the gate runs BEFORE the write — a denial returns an
+ * `err({ kind: 'runtime', ... })` with the gate's audit message. The
+ * filesystem is never touched on deny.
+ *
+ * Encoding: UTF-8 only at this layer. Binary writes are out of scope for
+ * Phase 1; if needed, a future `file_write_binary` primitive lands with
+ * a Base64-encoded `content` arg.
+ *
+ * Imports from: zod, node:fs/promises, node:path, ../runtime/result.js,
+ *   ../runtime/capability_gate.js, ./registry.js.
+ * Imported by: src/functions/index.ts (registry wiring).
+ */
+import type { CapabilityGate } from '../runtime/capability_gate.js';
+import type { FunctionRegistry } from './registry.js';
+/**
+ * Register the `file_write` primitive. `cwd` resolves relative paths so
+ * the gate sees an absolute path (built-in path denies use absolute
+ * minimatch globs).
+ */
+export declare function registerFileWriteFunction(registry: FunctionRegistry, opts: {
+    gate: CapabilityGate;
+    cwd?: string;
+}): void;
+//# sourceMappingURL=file_write.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file_write.d.ts","sourceRoot":"","sources":["../../src/functions/file_write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAGpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AActD;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3C,IAAI,CAyCN"}

package/dist/functions/file_write.js

@@ -0,0 +1,86 @@
+/**
+ * `file_write` primitive — gated arbitrary-path file writer (AUTO.3).
+ *
+ * Distinct from `write_state` (in `./state.ts`), which writes ONLY into
+ * `~/.opensquid/sessions/<id>/state/` or `~/.opensquid/packs/<id>/state/`.
+ * `file_write` is the primitive that handles user-content writes (skill
+ * outputs, generated reports, ingest results) and so must pass through
+ * the capability gate.
+ *
+ * Atomicity: tmp-file + rename, same idiom as `state.atomicWriteJson`.
+ *
+ * Gate posture: the gate runs BEFORE the write — a denial returns an
+ * `err({ kind: 'runtime', ... })` with the gate's audit message. The
+ * filesystem is never touched on deny.
+ *
+ * Encoding: UTF-8 only at this layer. Binary writes are out of scope for
+ * Phase 1; if needed, a future `file_write_binary` primitive lands with
+ * a Base64-encoded `content` arg.
+ *
+ * Imports from: zod, node:fs/promises, node:path, ../runtime/result.js,
+ *   ../runtime/capability_gate.js, ./registry.js.
+ * Imported by: src/functions/index.ts (registry wiring).
+ */
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { z } from 'zod';
+import { err, ok } from '../runtime/result.js';
+const FileWriteArgs = z.object({
+    path: z.string().min(1),
+    content: z.string(),
+});
+async function atomicWriteText(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+    await writeFile(tmp, value, 'utf8');
+    await rename(tmp, path);
+}
+/**
+ * Register the `file_write` primitive. `cwd` resolves relative paths so
+ * the gate sees an absolute path (built-in path denies use absolute
+ * minimatch globs).
+ */
+export function registerFileWriteFunction(registry, opts) {
+    const baseDir = opts.cwd ?? process.cwd();
+    // DURABLE.2 — atomic tmp+rename file write. Side-effecting (touches the
+    // filesystem) and gate-checked (one CapabilityGate roundtrip). Re-running
+    // on resume would re-write the file — harmless for content-identical
+    // writes, but a wasted gate check + write. Checkpoint so resume restores
+    // the `{ path, bytes }` result without re-writing. NOT memoizable: a
+    // memoized hit would silently skip the actual filesystem write, which is
+    // the entire point of the primitive.
+    registry.register({
+        name: 'file_write',
+        argSchema: FileWriteArgs,
+        durable: true,
+        memoizable: false,
+        costEstimateMs: 5,
+        execute: async ({ path, content }, ctx) => {
+            const absolute = isAbsolute(path) ? path : resolve(baseDir, path);
+            const verdict = await opts.gate.check({
+                pack: ctx.packId,
+                capability: 'file_write',
+                target: absolute,
+                context: { sessionId: ctx.sessionId },
+            });
+            if (!verdict.allowed) {
+                return err({
+                    kind: 'runtime',
+                    message: `file_write denied: ${verdict.message ?? verdict.source}`,
+                });
+            }
+            try {
+                await atomicWriteText(absolute, content);
+                return ok({ path: absolute, bytes: Buffer.byteLength(content, 'utf8') });
+            }
+            catch (e) {
+                return err({
+                    kind: 'runtime',
+                    message: `file_write(${path}): ${String(e)}`,
+                    cause: e,
+                });
+            }
+        },
+    });
+}
+//# sourceMappingURL=file_write.js.map

package/dist/functions/file_write.js.map

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

package/dist/functions/fsm.d.ts

@@ -0,0 +1,3 @@
+import type { FunctionRegistry } from './registry.js';
+export declare function registerFsmFunctions(registry: FunctionRegistry): void;
+//# sourceMappingURL=fsm.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fsm.d.ts","sourceRoot":"","sources":["../../src/functions/fsm.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAOtD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAoCrE"}

package/dist/functions/fsm.js

@@ -0,0 +1,62 @@
+/**
+ * T-PACK-FSM-STANDARDIZATION slice A3b — `read_fsm_state` / `advance_fsm`.
+ *
+ * Make a pack's declared lifecycle FSM (`Pack.fsm`, threaded as `ctx.packFsm`)
+ * usable from its OWN rules — closing the loop so a pack drives + gates on its
+ * machine without any change to the generic interpreter:
+ *
+ *   - `read_fsm_state()` → the current state string. Bind via `as` and gate:
+ *       - call: read_fsm_state
+ *         as: st
+ *       - call: verdict
+ *         if: st == "researching"
+ *         args: { level: block, message: "finish research first" }
+ *   - `advance_fsm({ event })` → fire an event; advances ONLY along a declared
+ *     transition (the total `step`), guards (`when`) evaluated through the
+ *     expression engine over the current bindings, then persists. Returns the
+ *     new state (== current when the event matched nothing — total/no-op).
+ *
+ * Both return `null` when the pack ships no `fsm.yaml` (`ctx.packFsm`
+ * undefined) — a pack without a lifecycle simply has nothing to read/advance.
+ */
+import { z } from 'zod';
+import { evalCondition } from '../runtime/evaluator/expression/index.js';
+import { advanceFsmState, readFsmState, readFsmStateRaw } from '../runtime/fsm_state.js';
+import { ok } from '../runtime/result.js';
+// Optional `pack`: read ANOTHER pack's lifecycle state (cross-pack gating).
+// Omitted → the calling pack's own FSM (via ctx.packFsm).
+const ReadFsmStateArgs = z.object({ pack: z.string().min(1).optional() }).strict();
+const AdvanceFsmArgs = z.object({ event: z.string().min(1) }).strict();
+export function registerFsmFunctions(registry) {
+    registry.register({
+        name: 'read_fsm_state',
+        argSchema: ReadFsmStateArgs,
+        durable: false,
+        memoizable: false,
+        costEstimateMs: 1,
+        execute: async ({ pack }, ctx) => {
+            // Cross-pack read: another pack's persisted state string (null if unstarted).
+            if (pack !== undefined)
+                return ok(await readFsmStateRaw(ctx.sessionId, pack));
+            // Own pack: full read with the threaded FSM (defaults to initial).
+            if (ctx.packFsm === undefined)
+                return ok(null);
+            return ok(await readFsmState(ctx.sessionId, ctx.packId, ctx.packFsm));
+        },
+    });
+    registry.register({
+        name: 'advance_fsm',
+        argSchema: AdvanceFsmArgs,
+        durable: false,
+        memoizable: false,
+        costEstimateMs: 2,
+        execute: async ({ event }, ctx) => {
+            if (ctx.packFsm === undefined)
+                return ok(null);
+            const now = new Date().toISOString();
+            const result = await advanceFsmState(ctx.sessionId, ctx.packId, ctx.packFsm, event, now, (expr) => evalCondition(expr, ctx.bindings));
+            return ok(result.next);
+        },
+    });
+}
+//# sourceMappingURL=fsm.js.map