mtech-ai-local-runner 0.1.55 → 0.1.56

package/README.md

@@ -1,3 +1,18 @@
+## 0.1.56: AI-first asks count only prompts a person typed
+
+Claude Code runs UserPromptSubmit for turns nobody typed as well: an asyncRewake wake, a task notification, a message
+from another session, a side session's brief (Work Item e1c08b33, Work Decision cc8817f9). The ask hook client now
+classifies each prompt on this Mac and tells the hub only whether a person typed it, never the text.
+- A prompt nobody typed marks the session as in a turn and does nothing else: it does not show an ask, does not count one
+  as seen and does not make the session the one asks go to.
+- A typed prompt within 10 s of a wake or a stop show does not count that ask as seen.
+- An ask pinned to a session in a turn is shown at the next typed prompt in any session that becomes its chosen session
+  (PR #421), or at that session's turn end.
+
+The hub still accepts the prompt events of an older hook client and counts them as typed. `asks.json` gains an optional
+`lastTurnStartAt` per session. A session that was already open before the integration was installed has no hooks: start
+a new session, or run `/reload-plugins` in the terminal.
+
 ## 0.1.55: guide hooks that steer AI sessions to the AI Gateway (disabled)
 
 The guide integration (Work Item d38d60f9) adds two hooks to Claude Code and Codex. Install it only on request:

package/dist/src/asks/hook-client.js

@@ -56,6 +56,32 @@ export function isHumanSession(app, env, _input, stateRoot) {
         return attended === "1";
     return INTERACTIVE_ENTRYPOINTS.has(env.CLAUDE_CODE_ENTRYPOINT ?? "");
 }
+/** The reminders a client app puts in front of what was submitted, typed or not. */
+const LEADING_REMINDERS = /^\s*(?:<system-reminder>[\s\S]*?<\/system-reminder>\s*)+/;
+/**
+ * How a turn nobody typed begins (Work Decision cc8817f9), as the 2026-10-26 transcripts recorded them. Claude Code runs
+ * UserPromptSubmit for these turns as well, and its hook input says nothing of where a prompt came from.
+ * - A Claude asyncRewake wake and a background task: a task notification.
+ * - The app's report of a side session's turn, and a message from another session.
+ * - A side session's first brief, written by the session that started it.
+ * - The summary that continues a compacted conversation, and an interruption marker.
+ * - This runner's own lines.
+ */
+const NOT_TYPED_PREFIXES = [
+    "<task-notification>", "<side-sessions-event>", "<cross-session-message", "<agent-message", "Another Claude session sent a message:",
+    "Background (from the session that started this one):", "This session is being continued from a previous conversation",
+    "[Request interrupted by user", "AI Gateway:",
+];
+/**
+ * True when a person typed this prompt. Only the answer leaves this client, never the text. A prompt that is not a
+ * string counts as typed, as every prompt did before this rule.
+ */
+export function isHumanPrompt(prompt) {
+    if (typeof prompt !== "string")
+        return true;
+    const rest = prompt.replace(LEADING_REMINDERS, "").trimStart();
+    return rest !== "" && !NOT_TYPED_PREFIXES.some(prefix => rest.startsWith(prefix));
+}
 /** Same rule as defaultStateRootFromEnv in src/config.ts, repeated so this client loads nothing else. */
 function stateRootFrom(env) {
     return env.XDG_STATE_HOME ? join(env.XDG_STATE_HOME, "mtec-ai-local-runner") : join(env.HOME ?? "", ".local", "state", "mtec-ai-local-runner");
@@ -107,7 +133,7 @@ function parseRecord(raw) {
     }
     return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
-/** Takes the session id, the cwd and Codex's stop_hook_active. Every other field, the prompt included, is ignored. */
+/** Takes the session id, the cwd and Codex's stop_hook_active. Every other field is ignored; the prompt is only classified (isHumanPrompt). */
 function hookFields(input) {
     const { session_id: sessionId, cwd, stop_hook_active: stopHookActive } = input;
     if (typeof sessionId !== "string" || !SESSION_ID.test(sessionId))
@@ -194,9 +220,10 @@ export async function runHookClient(argv, io) {
             io.stderr(text);
             return 2;
         }
-        const request = args.event === "stop"
-            ? { v: 1, op: "event", app: args.app, event: args.event, session_id: input.sessionId, cwd: input.cwd, stop_hook_active: input.stopHookActive }
-            : { v: 1, op: "event", app: args.app, event: args.event, session_id: input.sessionId, cwd: input.cwd };
+        const base = { v: 1, op: "event", app: args.app, event: args.event, session_id: input.sessionId, cwd: input.cwd };
+        const request = args.event === "stop" ? { ...base, stop_hook_active: input.stopHookActive }
+            : args.event === "prompt" ? { ...base, human: isHumanPrompt(record.prompt) }
+                : base;
         const text = await converse(socketPath, encodeLine(request), hubTimeoutMs, hubTimeoutMs, line => ({ done: true, value: parseEventResponse(line)?.text ?? null }));
         if (text === null || text === "")
             return 0;

package/dist/src/asks/hub-protocol.js

@@ -5,7 +5,9 @@ import { MAX_CWD_LENGTH, SESSION_ID, isApp, isHookEvent } from "./types.js";
  * may import nothing but ./types.js.
  *
  * Client to hub, one line, then the client waits without closing its side:
- *   {"v":1,"op":"event","app":"claude"|"codex","event":"session-start"|"prompt"|"session-end","session_id":…,"cwd":…}
+ *   {"v":1,"op":"event","app":"claude"|"codex","event":"session-start"|"session-end","session_id":…,"cwd":…}
+ *   {"v":1,"op":"event","app":"claude"|"codex","event":"prompt","session_id":…,"cwd":…,"human":true|false}
+ *                                                 (a client from before the flag sends no "human"; that prompt counts as typed)
  *   {"v":1,"op":"event","app":"codex","event":"stop","session_id":…,"cwd":…,"stop_hook_active":false}
  *   {"v":1,"op":"watch","app":"claude","session_id":…,"cwd":…}        (the Claude Stop watcher)
  *   {"v":1,"op":"status"}                                             (doctor)
@@ -68,6 +70,11 @@ export function parseHubRequest(line) {
             return null;
         return { v: 1, op: "event", app: "codex", event: "stop", session_id: value.session_id, cwd: value.cwd, stop_hook_active: value.stop_hook_active };
     }
+    if (value.event === "prompt" && Object.keys(value).length === 7) {
+        if (typeof value.human !== "boolean")
+            return null;
+        return { v: 1, op: "event", app: value.app, event: "prompt", session_id: value.session_id, cwd: value.cwd, human: value.human };
+    }
     if (Object.keys(value).length !== 6)
         return null;
     return { v: 1, op: "event", app: value.app, event: value.event, session_id: value.session_id, cwd: value.cwd };

package/dist/src/asks/inbox.js

@@ -83,7 +83,7 @@ export class AskInbox {
                     answer(null);
                     return;
                 }
-                const context = { app: request.app, sessionId: request.session_id, cwd: request.cwd, now: this.now() };
+                const context = { app: request.app, sessionId: request.session_id, cwd: request.cwd, now: this.now(), human: request.human !== false };
                 let text = null;
                 if (request.event === "session-start")
                     text = renderOutput(sessionStarted(this.state, context), { sessionId: request.session_id });

package/dist/src/asks/routing.js

@@ -19,6 +19,12 @@ export const MAX_ITEMS_PER_OUTPUT = 5;
 export const OPEN_PENDING_MS = 15 * 60 * 1000;
 /** At most 3 sessions opened per Mac in any hour. */
 export const OPEN_LIMIT = 3;
+/**
+ * A prompt this soon after a wake or a stop show does not count as seen (Work Decision cc8817f9). Claude submits the
+ * woken turn itself within a few seconds, and a person needs longer to read the ask and type. An early typed prompt
+ * leaves the item shown: the next one counts, or the Gateway's Slack fallback covers it.
+ */
+export const SEEN_AFTER_CONTINUATION_MS = 10_000;
 export function hashSessionId(sessionId) {
     return createHash("sha256").update(sessionId, "utf8").digest("hex");
 }
@@ -29,8 +35,10 @@ export function isLive(session, now) {
 export function humanPromptWithin(session, now) {
     return session.lastPromptAt !== null && now - session.lastPromptAt <= WAKE_WINDOW_MS;
 }
+/** A turn started by a typed prompt or by one nobody typed has not ended yet. */
 export function turnInProgress(session) {
-    return session.lastPromptAt !== null && (session.lastTurnEndAt === null || session.lastPromptAt > session.lastTurnEndAt);
+    const started = Math.max(session.lastPromptAt ?? -1, session.lastTurnStartAt ?? -1);
+    return started >= 0 && (session.lastTurnEndAt === null || started > session.lastTurnEndAt);
 }
 export function wakesLeft(session, now) {
     return WAKE_LIMIT - session.wakes.filter(at => now - at < WAKE_PERIOD_MS).length;
@@ -64,7 +72,8 @@ export function chooseSession(item, state, now) {
  * Where a delivery that is not shown yet goes now:
  * - no live session, or the chosen one had no human prompt in 30 minutes: a notification, then the next
  *   SessionStart or prompt in any session;
- * - the chosen session is in a turn: pinned there, shown at its turn end or next prompt;
+ * - the chosen session is in a turn: pinned there, shown at its turn end or at the next prompt in any session that
+ *   becomes the chosen one by that prompt (see promptSubmitted);
  * - an idle Claude session whose Stop watcher waits, under its hourly limit: woken now;
  * - otherwise (an idle Codex session, no watcher, or the limit reached): a notification.
  */
@@ -168,13 +177,30 @@ export function sessionStarted(state, context) {
         markShown(item, key, context.app, "session_start", context.now);
     return output;
 }
-/** UserPromptSubmit: earlier items shown in this session become seen; waiting items are shown and seen at once. */
+/**
+ * UserPromptSubmit. A prompt nobody typed only starts a turn: it shows nothing, counts nothing as seen and is not a human
+ * prompt for routing (Work Decision cc8817f9).
+ *
+ * A typed prompt makes earlier items shown in this session seen, except those a wake or a stop showed under
+ * SEEN_AFTER_CONTINUATION_MS ago. Waiting items are shown and seen at once. So is an item pinned to another session that
+ * this prompt makes the chosen session for it: the person just typed here, while that session is still in its turn.
+ * Without this the next plan pinned the item here to wait for this turn's end, and a prompt elsewhere could move it on
+ * again before then (live test 2026-10-26). An answer that names a live session stays there, because the session that
+ * asked is still chosen first.
+ */
 export function promptSubmitted(state, context) {
     const { key, session } = touch(state, context);
+    if (context.human === false) {
+        session.lastTurnStartAt = context.now;
+        return { items: [], more: [] };
+    }
     session.lastPromptAt = context.now;
-    for (const item of itemsWhere(state, item => item.phase === "shown" && item.sessionKey === key))
+    const settled = (item) => (item.shownVia !== "rewake" && item.shownVia !== "stop")
+        || item.shownAt === null || context.now - item.shownAt >= SEEN_AFTER_CONTINUATION_MS;
+    for (const item of itemsWhere(state, item => item.phase === "shown" && item.sessionKey === key && settled(item)))
         markSeen(item, context.app, context.now);
-    const output = selectForOutput(dueFor(state, key));
+    const takenOver = itemsWhere(state, item => item.phase === "pinned" && item.sessionKey !== key && chooseSession(item, state, context.now) === key);
+    const output = selectForOutput([...dueFor(state, key), ...takenOver]);
     for (const item of everyItem(output)) {
         markShown(item, key, context.app, "prompt", context.now);
         markSeen(item, context.app, context.now);

package/dist/src/asks/store.js

@@ -100,7 +100,11 @@ function normalizeSession(key, value) {
         return null;
     if (!Array.isArray(v.wakes) || !v.wakes.every(isTime))
         return null;
+    // Stored before Work Decision cc8817f9 a session has no turn start; one that is not a time is dropped with the session.
+    if (v.lastTurnStartAt !== undefined && !isTime(v.lastTurnStartAt))
+        return null;
     return { app: v.app, sessionId: v.sessionId, cwd: v.cwd, startedAt: v.startedAt, lastEventAt: v.lastEventAt, lastPromptAt: v.lastPromptAt,
+        ...(v.lastTurnStartAt === undefined ? {} : { lastTurnStartAt: v.lastTurnStartAt }),
         lastTurnEndAt: v.lastTurnEndAt, endedAt: v.endedAt, wakes: [...v.wakes] };
 }
 /**

package/dist/src/daemon/job-poller.js

@@ -0,0 +1,42 @@
+export class JobPoller {
+    deps;
+    stopped = false;
+    failures = 0;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    stop() { this.stopped = true; }
+    async tick() {
+        if (this.stopped)
+            return;
+        let stage = "heartbeat";
+        try {
+            await this.deps.heartbeat?.();
+            stage = "wait";
+            const claim = await this.deps.wait();
+            stage = "execute";
+            if (claim.status === "claimed" && claim.job)
+                await this.deps.execute(claim.job);
+            this.failures = 0;
+        }
+        catch {
+            try {
+                this.deps.reportError?.({ stage, code: stage === "execute" ? "EXECUTION_UNACKNOWLEDGED" : "GATEWAY_UNAVAILABLE" });
+            }
+            catch { /* Observational logging cannot bypass stop/backoff or discard recovery state. */ }
+            // Unknown execution/terminal outcomes must reconcile before any new claim.
+            if (stage === "execute") {
+                this.stop();
+                return;
+            }
+            this.failures += 1;
+            const base = Math.min(30_000, 1000 * (2 ** Math.min(5, this.failures - 1)));
+            const jitter = Math.floor(base * 0.2 * (this.deps.random ?? Math.random)());
+            await this.deps.delay(base + jitter);
+        }
+    }
+    async run() {
+        while (!this.stopped)
+            await this.tick();
+    }
+}

package/dist/src/daemon/session-open-poller.js

@@ -0,0 +1,123 @@
+const MINIMUM_CYCLE_MS = 1000;
+/** Pauses before the second and third report attempts. The server treats a repeat report as idempotent. */
+const REPORT_RETRY_DELAYS_MS = [1000, 2000];
+/** The caught error's own failure code (a GatewayToolError code such as GATEWAY_HTTP_401), never its message, which may carry server text. */
+function causeOf(error) {
+    const code = error?.code;
+    return typeof code === "string" && /^[A-Z0-9_]{1,64}$/.test(code) ? code : undefined;
+}
+/** Resolves after the delay or at once on abort, and never leaves a listener on a long-lived signal. */
+export function abortableDelay(milliseconds, signal) {
+    return new Promise(resolve => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const onAbort = () => { clearTimeout(timer); resolve(); };
+        const timer = setTimeout(() => { signal.removeEventListener("abort", onAbort); resolve(); }, milliseconds);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+export class SessionOpenPoller {
+    deps;
+    controller = new AbortController();
+    failures = 0;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    stop() { this.controller.abort(); }
+    fail(stage, error, code = `SESSION_OPEN_${stage.toUpperCase()}_FAILED`) {
+        const cause = causeOf(error);
+        try {
+            this.deps.reportError?.({ stage, code, ...(cause ? { cause } : {}) });
+        }
+        catch { /* Logging cannot stop the loop. */ }
+    }
+    async pause(milliseconds, signal) {
+        await this.deps.delay(milliseconds, signal).catch(() => undefined);
+    }
+    /** Opens one claimed request and reports it. A failure here never reaches the rest of the batch. */
+    async handle(request, signal) {
+        let result;
+        try {
+            result = await this.deps.open(request);
+        }
+        catch (error) {
+            if (!signal.aborted)
+                this.fail("open", error);
+            return;
+        }
+        const openId = request?.open_id;
+        if (typeof openId !== "string" || openId === "")
+            return;
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                await this.deps.report(openId, result, signal);
+                return;
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return;
+                const retryDelay = REPORT_RETRY_DELAYS_MS[attempt];
+                if (retryDelay === undefined) {
+                    this.fail("report", error);
+                    return;
+                }
+                await this.pause(retryDelay, signal);
+                if (signal.aborted)
+                    return;
+            }
+        }
+    }
+    async tick() {
+        const signal = this.controller.signal;
+        if (signal.aborted)
+            return;
+        const now = this.deps.now ?? (() => performance.now());
+        const started = now();
+        let opens;
+        let retryAfterSeconds;
+        try {
+            ({ opens, retryAfterSeconds } = await this.deps.wait(signal));
+        }
+        catch (error) {
+            if (signal.aborted)
+                return;
+            this.fail("wait", error);
+            this.failures += 1;
+            const base = Math.min(30_000, 1000 * (2 ** Math.min(5, this.failures - 1)));
+            const jitter = Math.floor(base * 0.2 * (this.deps.random ?? Math.random)());
+            await this.pause(base + jitter, signal);
+            return;
+        }
+        this.failures = 0;
+        const claimed = Array.isArray(opens) ? opens : [];
+        for (const request of claimed) {
+            if (signal.aborted)
+                return;
+            await this.handle(request, signal);
+        }
+        if (claimed.length > 0 || signal.aborted)
+            return;
+        // A wait that returns at once with nothing (a Gateway wait of 0) must not become a hot loop, and while the Gateway's
+        // session open switch is off it asks for a longer pause (retry_after_seconds). The clock is monotonic and clamped.
+        const elapsed = Math.max(0, now() - started);
+        const remainder = elapsed < MINIMUM_CYCLE_MS ? MINIMUM_CYCLE_MS - elapsed : 0;
+        const wanted = retryAfterSeconds === undefined ? remainder : Math.max(remainder, retryAfterSeconds * 1000);
+        if (wanted > 0)
+            await this.pause(wanted, signal);
+    }
+    async run() {
+        const signal = this.controller.signal;
+        while (!signal.aborted) {
+            try {
+                await this.tick();
+            }
+            catch {
+                this.fail("wait", undefined, "SESSION_OPEN_LOOP_FAILED");
+                if (!signal.aborted)
+                    await this.pause(1000, signal);
+            }
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtech-ai-local-runner",
-  "version": "0.1.55",
+  "version": "0.1.56",
   "private": false,
   "license": "UNLICENSED",
   "bin": {