@lelouchhe/webagent 0.9.0 → 0.10.0

package/lib/task-path.js

@@ -0,0 +1,131 @@
+/** Server-side syntax primitives for task-target commands. */
+/** An invalid command head is rejected rather than being guessed as ordinary input. */
+export class TaskPathParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TaskPathParseError";
+    }
+}
+function isWhitespace(char) {
+    return /\s/u.test(char);
+}
+function skipWhitespace(source, offset) {
+    let cursor = offset;
+    while (cursor < source.length && isWhitespace(source[cursor]))
+        cursor++;
+    return cursor;
+}
+/**
+ * Parse one deliberately small shell-style word.
+ *
+ * Quotes and backslash escapes exist only as input syntax. This is not a shell:
+ * variables, command substitution, globbing, comments, and operators are all
+ * ordinary characters.
+ */
+function parseShellWord(source, start) {
+    let cursor = start;
+    let value = "";
+    let consumed = false;
+    while (cursor < source.length && !isWhitespace(source[cursor])) {
+        const char = source[cursor];
+        if (char === "\\") {
+            if (cursor + 1 >= source.length) {
+                throw new TaskPathParseError("Target ends with an incomplete escape");
+            }
+            value += source[cursor + 1];
+            cursor += 2;
+            consumed = true;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            const quote = char;
+            cursor++;
+            consumed = true;
+            let closed = false;
+            while (cursor < source.length) {
+                const quoted = source[cursor];
+                if (quoted === quote) {
+                    cursor++;
+                    closed = true;
+                    break;
+                }
+                if (quote === '"' && quoted === "\\") {
+                    if (cursor + 1 >= source.length) {
+                        throw new TaskPathParseError("Target ends with an incomplete escape inside double quotes");
+                    }
+                    value += source[cursor + 1];
+                    cursor += 2;
+                    continue;
+                }
+                value += quoted;
+                cursor++;
+            }
+            if (!closed) {
+                throw new TaskPathParseError("Target contains an unterminated quote");
+            }
+            continue;
+        }
+        value += char;
+        cursor++;
+        consumed = true;
+    }
+    if (!consumed || value.length === 0) {
+        throw new TaskPathParseError("Task command requires a non-empty target");
+    }
+    return { value, end: cursor };
+}
+/**
+ * Decode a slash-separated path without resolving it against a task tree or
+ * filesystem. Consecutive separators are normalized; `.` and `..` remain so
+ * the receiving resolver can enforce its own root and visibility policy.
+ */
+export function parseTaskPath(target) {
+    // An empty target is a bare `+`/`@`: the caller lists its default scope
+    // instead of resolving a path.
+    if (!target)
+        return { absolute: false, segments: [] };
+    const absolute = target.startsWith("/");
+    const segments = target.split("/").filter(Boolean);
+    return {
+        absolute,
+        segments,
+        ...(target.endsWith("/") ? { trailingSlash: true } : {}),
+    };
+}
+/**
+ * Parse the command marker and its target word. Policy and path resolution are
+ * intentionally outside this module; callers retain the raw remainder as the
+ * eventual message body or creation brief.
+ */
+export function parseTaskCommand(source) {
+    const markerStart = skipWhitespace(source, 0);
+    let marker;
+    let targetStart;
+    if (source.startsWith("@!", markerStart)) {
+        marker = "@!";
+        targetStart = markerStart + 2;
+    }
+    else if (source[markerStart] === "+" || source[markerStart] === "@") {
+        marker = source[markerStart];
+        targetStart = markerStart + 1;
+    }
+    else {
+        throw new TaskPathParseError("Task command must start with +, @, or @!");
+    }
+    const start = skipWhitespace(source, targetStart);
+    if (start >= source.length) {
+        return {
+            marker,
+            target: "",
+            path: { absolute: false, segments: [] },
+            remainder: source.slice(targetStart),
+        };
+    }
+    const word = parseShellWord(source, start);
+    return {
+        marker,
+        target: word.value,
+        path: parseTaskPath(word.value),
+        remainder: source.slice(word.end),
+    };
+}

package/lib/{session-state.js → task-state.js}

@@ -1,6 +1,6 @@
 /**
- * Per-session runtime state: single source of truth for "what state is this
- * session in right now" (busy / streaming / pending permissions / plan).
+ * Per-task runtime state: single source of truth for "what state is this
+ * task in right now" (busy / streaming / pending permissions / plan).
  *
  * The frontend fetches a full snapshot on connect / reconnect / after long
  * backgrounding, then applies incremental `state_patch` SSE events. This
@@ -90,31 +90,31 @@ function hasRuntimeChanges(current, patch) {
     }
     return false;
 }
-export class SessionStateManager {
+export class TaskStateManager {
     states = new Map();
     listeners = new Set();
     cancelTimers = new Map();
     /** Get current state (creates default entry on first access). */
-    getState(sessionId) {
-        let s = this.states.get(sessionId);
+    getState(taskId) {
+        let s = this.states.get(taskId);
         if (!s) {
             s = defaultState();
-            this.states.set(sessionId, s);
+            this.states.set(taskId, s);
         }
         return s;
     }
-    /** Read streaming state without creating runtime state for an unseen session. */
-    peekStreaming(sessionId) {
-        const streaming = this.states.get(sessionId)?.runtime.streaming;
+    /** Read streaming state without creating runtime state for an unseen task. */
+    peekStreaming(taskId) {
+        const streaming = this.states.get(taskId)?.runtime.streaming;
         return streaming ? { ...streaming } : { assistant: false, thinking: false };
     }
     /**
-     * Merge a patch into the session's runtime state. Bumps seq and notifies
+     * Merge a patch into the task's runtime state. Bumps seq and notifies
      * listeners only when the patch actually changes something (no-op patches
      * are dropped silently).
      */
-    patch(sessionId, patch) {
-        const state = this.getState(sessionId);
+    patch(taskId, patch) {
+        const state = this.getState(taskId);
         const runtimeChanged = hasRuntimeChanges(state.runtime, patch.runtime);
         if (!runtimeChanged)
             return;
@@ -152,7 +152,7 @@ export class SessionStateManager {
         state.seq += 1;
         const event = {
             type: "state_patch",
-            sessionId,
+            taskId,
             seq: state.seq,
             patch,
         };
@@ -166,37 +166,60 @@ export class SessionStateManager {
             this.listeners.delete(cb);
         };
     }
-    /** Clear all state for a session (call from SessionManager.deleteSession). */
-    delete(sessionId) {
-        this.states.delete(sessionId);
-        const t = this.cancelTimers.get(sessionId);
+    /** Clear all state for a task (call from TaskManager.deleteTask). */
+    delete(taskId) {
+        this.states.delete(taskId);
+        const t = this.cancelTimers.get(taskId);
         if (t) {
             clearTimeout(t);
-            this.cancelTimers.delete(sessionId);
+            this.cancelTimers.delete(taskId);
         }
     }
-    /** Clear current plans for every known session (used on bridge reload). */
+    /**
+     * Reset a live task's runtime state to defaults without restarting the
+     * seq ledger. Used when rotating a task's ACP execution in place (clear):
+     * the WebAgent task identity survives, so clients that validate
+     * incremental `state_patch` events against their own lastStateSeq must keep
+     * seeing a monotonic seq. Hard-deleting the entry here would restart the
+     * server seq at 0; every post-rotation snapshot would then look
+     * "superseded" to the client and be dropped, leaving it permanently
+     * desynced (stuck busy). Broadcasts one patch when anything actually
+     * changed, mirroring the explicit reset patch used by the compaction path.
+     */
+    reset(taskId) {
+        this.clearCancelSafety(taskId);
+        this.patch(taskId, {
+            runtime: {
+                busy: null,
+                pendingPermissions: [],
+                streaming: { assistant: false, thinking: false },
+                plan: null,
+                contextUsage: null,
+            },
+        });
+    }
+    /** Clear current plans for every known task (used on bridge reload). */
     clearPlans() {
-        for (const [sessionId, state] of this.states) {
+        for (const [taskId, state] of this.states) {
             if (state.runtime.plan !== null) {
-                this.patch(sessionId, { runtime: { plan: null } });
+                this.patch(taskId, { runtime: { plan: null } });
             }
         }
     }
-    /** Clear context usage for every known session on bridge teardown. */
+    /** Clear context usage for every known task on bridge teardown. */
     clearContextUsage() {
-        for (const [sessionId, state] of this.states) {
+        for (const [taskId, state] of this.states) {
             if (state.runtime.contextUsage !== null) {
-                this.patch(sessionId, { runtime: { contextUsage: null } });
+                this.patch(taskId, { runtime: { contextUsage: null } });
             }
         }
     }
-    /** Clear active stream markers for every known session on bridge teardown. */
+    /** Clear active stream markers for every known task on bridge teardown. */
     clearStreaming() {
-        for (const [sessionId, state] of this.states) {
+        for (const [taskId, state] of this.states) {
             if (state.runtime.streaming.assistant ||
                 state.runtime.streaming.thinking) {
-                this.patch(sessionId, {
+                this.patch(taskId, {
                     runtime: {
                         streaming: { assistant: false, thinking: false },
                     },
@@ -207,23 +230,23 @@ export class SessionStateManager {
     /**
      * Backend acknowledgement timer for cancel: if the same agent prompt is
      * still pending after `timeoutMs`, mark the request unconfirmed.
-     * A second arm on the same session replaces the existing timer.
+     * A second arm on the same task replaces the existing timer.
      */
-    armCancelSafety(sessionId, timeoutMs) {
+    armCancelSafety(taskId, timeoutMs) {
         if (timeoutMs <= 0)
             return;
-        const existing = this.cancelTimers.get(sessionId);
+        const existing = this.cancelTimers.get(taskId);
         if (existing)
             clearTimeout(existing);
         const t = setTimeout(() => {
-            this.cancelTimers.delete(sessionId);
-            const busy = this.getState(sessionId).runtime.busy;
+            this.cancelTimers.delete(taskId);
+            const busy = this.getState(taskId).runtime.busy;
             if (busy?.kind === "agent" && busy.cancelStatus === "requested") {
                 clog.warn("agent did not acknowledge", {
-                    sessionId: sessionId.slice(0, 8),
+                    taskId: taskId.slice(0, 8),
                     promptId: busy.promptId,
                 });
-                this.patch(sessionId, {
+                this.patch(taskId, {
                     runtime: {
                         busy: { ...busy, cancelStatus: "unconfirmed" },
                     },
@@ -232,23 +255,23 @@ export class SessionStateManager {
         }, timeoutMs);
         if (typeof t === "object" && "unref" in t)
             t.unref();
-        this.cancelTimers.set(sessionId, t);
+        this.cancelTimers.set(taskId, t);
     }
     /** Mark that a cancel notification was sent for the active agent prompt. */
-    markCancelRequested(sessionId) {
-        const busy = this.getState(sessionId).runtime.busy;
+    markCancelRequested(taskId) {
+        const busy = this.getState(taskId).runtime.busy;
         if (busy?.kind !== "agent")
             return;
-        this.patch(sessionId, {
+        this.patch(taskId, {
             runtime: { busy: { ...busy, cancelStatus: "requested" } },
         });
     }
     /** Cancel the safety net timer (e.g. when prompt_done arrives naturally). */
-    clearCancelSafety(sessionId) {
-        const t = this.cancelTimers.get(sessionId);
+    clearCancelSafety(taskId) {
+        const t = this.cancelTimers.get(taskId);
         if (t) {
             clearTimeout(t);
-            this.cancelTimers.delete(sessionId);
+            this.cancelTimers.delete(taskId);
         }
     }
 }

package/lib/task-tree-lock.js

@@ -0,0 +1,74 @@
+function normalize(spec) {
+    const exclusive = new Set(spec.exclusive ?? []);
+    const shared = new Set((spec.shared ?? []).filter((key) => !exclusive.has(key)));
+    return { shared, exclusive };
+}
+function conflicts(a, b) {
+    for (const key of a.exclusive) {
+        if (b.exclusive.has(key) || b.shared.has(key))
+            return true;
+    }
+    for (const key of a.shared) {
+        if (b.exclusive.has(key))
+            return true;
+    }
+    return false;
+}
+/**
+ * Small in-process hierarchical lock scheduler for one task tree.
+ *
+ * Requests are granted atomically, so callers never hold part of a lineage
+ * while waiting for another node. Compatible sibling requests can be active
+ * together; an earlier conflicting request keeps later requests from
+ * overtaking it. Releases are idempotent so failure paths can clean up safely.
+ */
+export class TaskTreeLock {
+    active = new Set();
+    pending = [];
+    acquire(spec) {
+        const request = normalize(spec);
+        if (request.shared.size === 0 && request.exclusive.size === 0) {
+            return Promise.resolve(() => { });
+        }
+        return new Promise((resolve) => {
+            this.pending.push({ ...request, resolve });
+            this.pump();
+        });
+    }
+    /** Acquire only when the scheduler is completely idle; otherwise skip. */
+    tryAcquire(spec) {
+        if (this.active.size > 0 || this.pending.length > 0)
+            return null;
+        const request = normalize(spec);
+        if (request.shared.size === 0 && request.exclusive.size === 0)
+            return () => { };
+        this.active.add(request);
+        return this.releaseFor(request);
+    }
+    pump() {
+        for (let i = 0; i < this.pending.length;) {
+            const candidate = this.pending[i];
+            const blockedByActive = [...this.active].some((active) => conflicts(candidate, active));
+            const blockedByEarlier = this.pending
+                .slice(0, i)
+                .some((earlier) => conflicts(candidate, earlier));
+            if (blockedByActive || blockedByEarlier) {
+                i++;
+                continue;
+            }
+            this.pending.splice(i, 1);
+            this.active.add(candidate);
+            candidate.resolve(this.releaseFor(candidate));
+        }
+    }
+    releaseFor(request) {
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.active.delete(request);
+            this.pump();
+        };
+    }
+}

package/lib/{sessions-anchor.js → tasks-anchor.js}

@@ -1,16 +1,16 @@
 import { mkdirSync, realpathSync } from "node:fs";
 import { join, sep } from "node:path";
 /**
- * Resolved absolute path to `<dataDir>/sessions/`. Pinned at server boot so
+ * Resolved absolute path to `<dataDir>/tasks/`. Pinned at server boot so
  * later `file://` URI construction and startsWith assertions all compare
- * against the same realpath (defends against macOS `/var → /private/var`
+ * against the same realpath (defends against macOS `/var to /private/var`
  * symlink + any future symlink swaps under `data_dir`).
  *
  * Throws if the directory cannot be created or resolved — fail fast at boot
  * rather than later when an attachment dispatch tries to use it.
  */
-export function resolveSessionsAnchor(dataDir) {
-    const dir = join(dataDir, "sessions");
+export function resolveTasksAnchor(dataDir) {
+    const dir = join(dataDir, "tasks");
     mkdirSync(dir, { recursive: true });
     const real = realpathSync(dir);
     // Normalize trailing separator so `startsWith(anchor + sep)` is the
@@ -19,10 +19,11 @@ export function resolveSessionsAnchor(dataDir) {
 }
 /**
  * Returns true iff `realpath` is a strict descendant of
- * `<sessionsAnchor>/<sessionId>/attachments/`. Both args must already be
+ * `<tasksAnchor>/<taskId>/attachments/` (on-disk directory is still
+ * `sessions`). Both args must already be
  * realpath-resolved (no `..`, no symlinks left).
  */
-export function isInsideSessionAttachments(sessionsAnchor, sessionId, realpath) {
-    const expected = sessionsAnchor + sep + sessionId + sep + "attachments" + sep;
+export function isInsideTaskAttachments(tasksAnchor, taskId, realpath) {
+    const expected = tasksAnchor + sep + taskId + sep + "attachments" + sep;
     return realpath.startsWith(expected);
 }

package/lib/tokens.js

@@ -11,7 +11,7 @@ import { randomBytes } from "node:crypto";
  *   - Internal IDs that aren't auth-bearing (client IDs, request IDs,
  *     error correlation IDs) — see sse-manager.ts, routes.ts, etc.
  *   - HMAC signing keys (image URL secret) — see server.ts.
- *   - UUIDs used as opaque labels (session IDs, msg IDs) — these
+ *   - UUIDs used as opaque labels (task IDs, msg IDs) — these
  *     are protocol identifiers, not credentials.
  *
  * Repo convention: `node:crypto` only. No `nanoid` / `uuid` deps.

package/lib/types.js

@@ -3,10 +3,10 @@ import { z } from "zod";
 const FROM_REF_ALLOWED = /^(cron|external):[A-Za-z0-9._\-+/]{1,120}$/;
 export const MessageIngressSchema = z.object({
     from_ref: z.string().min(1).max(128).regex(FROM_REF_ALLOWED, {
-        message: "from_ref must start with 'cron:' or 'external:' (reserved values and 'session:<id>' rejected in MVP)",
+        message: "from_ref must start with 'cron:' or 'external:' (reserved values and 'task:<id>' rejected in MVP)",
     }),
     from_label: z.string().max(64).optional(),
-    to: z.union([z.literal("user"), z.string().regex(/^session:[^\s]+$/)]),
+    to: z.union([z.literal("user"), z.string().regex(/^task:[^\s]+$/)]),
     deliver: z.enum(["silent", "inapp", "push"]).default("push"),
     dedup_key: z.string().max(128).optional(),
     title: z.string().min(1).max(256),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lelouchhe/webagent",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "A terminal-style web UI for ACP-compatible agents",
   "type": "module",
   "license": "MIT",
@@ -60,6 +60,7 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "^0.25.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@types/proper-lockfile": "^4.1.4",
     "@types/web-push": "^3.6.4",
     "better-sqlite3": "^12.6.2",
@@ -92,5 +93,10 @@
     "prettier": "^3.8.3",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.59.0"
+  },
+  "allowScripts": {
+    "better-sqlite3@12.6.2": true,
+    "esbuild@0.27.3": true,
+    "fsevents@2.3.2": true
   }
 }