@lelouchhe/webagent 0.9.0 → 0.10.0

package/lib/server.js

@@ -7,8 +7,10 @@ import { setLogLevel, log } from "./log.js";
 import { AgentBridge } from "./bridge.js";
 import { agentKeyFromCommand } from "./agent-key.js";
 import { Store } from "./store.js";
-import { SessionManager } from "./session-manager.js";
-import { TitleService } from "./title-service.js";
+import { TaskManager } from "./task-manager.js";
+import { CapabilityStore } from "./mcp/capability.js";
+import { createMcpEndpoint } from "./mcp/server.js";
+import { createMcpTaskToolHost } from "./mcp/task-host.js";
 import { createRequestHandler } from "./routes.js";
 import { handleAgentEvent } from "./event-handler.js";
 import { PushService } from "./push-service.js";
@@ -20,7 +22,7 @@ import { startMessageCleanup } from "./message-cleanup.js";
 import { startSharePreviewCleanup, } from "./share/cleanup.js";
 import { AuthStore } from "./auth-store.js";
 import { join as pathJoin } from "node:path";
-import { resolveSessionsAnchor } from "./sessions-anchor.js";
+import { resolveTasksAnchor } from "./tasks-anchor.js";
 import { runStartupChecks } from "./startup-checks.js";
 import { AttachmentDispatcher } from "./attachment-dispatch.js";
 import { buildBridgeEventHandlerConfig as _buildBridgeEventHandlerConfig } from "./bridge-event-config.js";
@@ -55,12 +57,13 @@ const PKG_VERSION = (() => {
 })();
 // --- Core dependencies ---
 const store = new Store(config.data_dir, agentKeyFromCommand(preflight.agentCmd));
+store.ensureRootTask(config.default_cwd);
 console.log(`[store] using ${config.data_dir}/`);
-// Pin <data_dir>/sessions realpath at boot so all later anchor checks
+// Pin <data_dir>/tasks realpath at boot so all later anchor checks
 // (file:// URI construction, permission interceptor) compare against the
 // same canonical path. Defends against macOS /var → /private/var.
-const sessionsAnchor = resolveSessionsAnchor(config.data_dir);
-const attachmentDispatcher = new AttachmentDispatcher(store, sessionsAnchor, {
+const tasksAnchor = resolveTasksAnchor(config.data_dir);
+const attachmentDispatcher = new AttachmentDispatcher(store, tasksAnchor, {
     warn: (msg) => {
         console.warn(msg);
     },
@@ -76,8 +79,14 @@ setInterval(() => {
         .scope("attachment-interceptor")
         .info("counters", { ...attachmentInterceptorCounters });
 }, ATTACHMENT_INTERCEPTOR_DUMP_MS).unref();
-const sessions = new SessionManager(store, config.default_cwd, config.data_dir);
-const titleService = new TitleService(store, sessions, config.default_cwd, config.title.models);
+// Per-task MCP capability store; minted/revoked by TaskManager. The
+// MCP endpoint authenticates against it. Tokens are in-memory
+// only, so a restart invalidates every outstanding capability.
+const capabilities = new CapabilityStore();
+// Agent subprocesses run on the same host as WebAgent, so the MCP server
+// URL is always loopback even when the HTTP listener binds elsewhere.
+const mcpBaseUrl = `http://127.0.0.1:${config.port}`;
+const tasks = new TaskManager(store, config.default_cwd, config.data_dir, capabilities, mcpBaseUrl);
 const sseManager = new SseManager();
 const clientRegistry = new ClientRegistry();
 const pushService = new PushService(store, config.data_dir, config.push.vapid_subject, {
@@ -99,12 +108,46 @@ const attachmentSecret = randomBytes(32);
 // within one heartbeat interval (≤15s).
 sseManager.setRevocationCheck((tokenName) => !authStore.hasTokenName(tokenName));
 sseManager.setAttachmentSecret(attachmentSecret);
-sseManager.setLabelMapProvider((sessionId) => sessions.getLabelMap(sessionId));
-// Broadcast runtime state patches to all SSE clients interested in the session.
-sessions.state.onPatch((event) => {
+sseManager.setLabelMapProvider((taskId) => tasks.getLabelMap(taskId));
+// Broadcast runtime state patches to all SSE clients interested in the task.
+tasks.state.onPatch((event) => {
     sseManager.broadcast(event);
 });
 let bridge = null;
+const mcpTaskTools = createMcpTaskToolHost({
+    store,
+    tasks,
+    getBridge: () => bridge,
+    cancelTimeoutMs: config.limits.cancel_timeout,
+    broadcastCollaboration: ({ messageId, sourceTaskId, targetTaskId, title, body, }) => {
+        for (const projection of store.listCollaborationProjections(messageId)) {
+            sseManager.broadcast({
+                type: "system_message",
+                taskId: projection.task_id,
+                kind: "collaboration",
+                messageId,
+                sourceTaskId,
+                targetTaskId,
+                role: projection.role,
+                title,
+                body,
+            });
+        }
+    },
+    broadcastTaskCreated: ({ messageId, sourceTaskId, targetTaskId, title, body, }) => {
+        sseManager.broadcast({
+            type: "system_message",
+            taskId: sourceTaskId,
+            kind: "task_created",
+            messageId,
+            sourceTaskId,
+            targetTaskId,
+            role: "source",
+            title,
+            body,
+        });
+    },
+});
 const messageCleanup = startMessageCleanup(store, config.messages.unprocessed_ttl_days, (pendingCount) => {
     sseManager.broadcastGlobal({ type: "inbox_count_changed", pendingCount });
 });
@@ -112,10 +155,9 @@ let sharePreviewCleanup = null;
 // --- HTTP server ---
 const requestHandler = createRequestHandler({
     store,
-    sessions,
+    tasks,
     sseManager,
     clientRegistry,
-    titleService,
     getBridge: () => bridge,
     publicDir: PUBLIC_DIR,
     dataDir: config.data_dir,
@@ -127,6 +169,11 @@ const requestHandler = createRequestHandler({
     ticketStore,
     attachmentSecret,
     shareConfig: config.share,
+    mcpEndpoint: createMcpEndpoint({
+        capabilities,
+        isTaskActive: (taskId) => tasks.isMcpSessionActive(taskId),
+        taskTools: mcpTaskTools,
+    }),
 });
 const server = createServer((req, res) => {
     void requestHandler(req, res);
@@ -147,7 +194,7 @@ async function initBridge(agentCmd) {
         },
     });
     b.on("event", (event) => {
-        handleAgentEvent(event, sessions, store, b, eventHandlerConfig, sseManager, pushService, clientRegistry);
+        handleAgentEvent(event, tasks, store, b, eventHandlerConfig, sseManager, pushService, clientRegistry);
     });
     await b.start();
     bridge = b;
@@ -159,7 +206,7 @@ async function shutdown() {
     sseManager.stopHeartbeat();
     messageCleanup.stop();
     sharePreviewCleanup?.stop();
-    sessions.killAllBashProcs();
+    tasks.killAllBashProcs();
     await bridge?.shutdown();
     await authStore.close();
     store.close();
@@ -199,7 +246,8 @@ server.listen(config.port, config.host, () => {
         try {
             await initBridge(agentCmd);
             console.log(`[bridge] ready`);
-            sessions.hydrate();
+            await tasks.ensureRootTask(bridge);
+            tasks.hydrate();
         }
         catch (err) {
             console.error(`[bridge] failed to start:`, err);

package/lib/share/routes.js

@@ -9,7 +9,7 @@ import { enrichStoredEventsForDisplay } from "../attachment-labels.js";
 import { log } from "../log.js";
 import { HTTP_STATUS } from "../http-status.js";
 const slog = log.scope("share");
-// In-flight dedup for concurrent POST /share on the same session.
+// In-flight dedup for concurrent POST /share on the same task.
 // First caller does the work; concurrent callers await the same promise.
 // Idempotent because the body re-checks for an existing preview before
 // inserting.
@@ -79,9 +79,9 @@ function json(res, status, body) {
  *
  * URL space claimed:
  *   /s, /s/:token                       (viewer — C3)
- *   /api/v1/sessions/:id/share          (preview create — C2 here)
- *   /api/v1/sessions/:id/share/preview  (preview read — C2 here)
- *   /api/v1/sessions/:id/share/publish  (activate — C3)
+ *   /api/v1/tasks/:id/share          (preview create — C2 here)
+ *   /api/v1/tasks/:id/share/preview  (preview read — C2 here)
+ *   /api/v1/tasks/:id/share/publish  (activate — C3)
  *   /api/v1/shares, /api/v1/shares/:t   (owner list/patch — C4)
  *   /api/v1/shared/:token               (public viewer JSON — C3)
  */
@@ -119,20 +119,20 @@ export async function handleShareRoutes(req, res, deps) {
         res.end("share token required");
         return true;
     }
-    // POST /api/v1/sessions/:id/share — create preview
-    const createMatch = url.match(/^\/api\/v1\/sessions\/([^/?]+)\/share\/?(?:\?.*)?$/);
+    // POST /api/v1/tasks/:id/share — create preview
+    const createMatch = url.match(/^\/api\/v1\/tasks\/([^/?]+)\/share\/?(?:\?.*)?$/);
     if (createMatch && method === "POST") {
         await handlePreviewCreate(req, res, deps, decodeURIComponent(createMatch[1]));
         return true;
     }
-    // GET /api/v1/sessions/:id/share/preview — read preview + staleness
-    const previewMatch = url.match(/^\/api\/v1\/sessions\/([^/?]+)\/share\/preview\/?(?:\?.*)?$/);
+    // GET /api/v1/tasks/:id/share/preview — read preview + staleness
+    const previewMatch = url.match(/^\/api\/v1\/tasks\/([^/?]+)\/share\/preview\/?(?:\?.*)?$/);
     if (previewMatch && method === "GET") {
         await handlePreviewRead(req, res, deps, decodeURIComponent(previewMatch[1]));
         return true;
     }
-    // POST /api/v1/sessions/:id/share/publish — promote preview to public
-    const publishMatch = url.match(/^\/api\/v1\/sessions\/([^/?]+)\/share\/publish\/?(?:\?.*)?$/);
+    // POST /api/v1/tasks/:id/share/publish — promote preview to public
+    const publishMatch = url.match(/^\/api\/v1\/tasks\/([^/?]+)\/share\/publish\/?(?:\?.*)?$/);
     if (publishMatch && method === "POST") {
         await handlePublish(req, res, deps, decodeURIComponent(publishMatch[1]));
         return true;
@@ -143,13 +143,13 @@ export async function handleShareRoutes(req, res, deps) {
         await handleSharedEvents(res, deps, sharedEventsMatch[1]);
         return true;
     }
-    const revokeMatch = url.match(/^\/api\/v1\/sessions\/([^/?]+)\/share\/?(?:\?.*)?$/);
-    // DELETE /api/v1/sessions/:id/share — hard-delete share row
+    const revokeMatch = url.match(/^\/api\/v1\/tasks\/([^/?]+)\/share\/?(?:\?.*)?$/);
+    // DELETE /api/v1/tasks/:id/share — hard-delete share row
     if (revokeMatch && method === "DELETE") {
         await handleRevoke(req, res, deps, decodeURIComponent(revokeMatch[1]));
         return true;
     }
-    // PATCH /api/v1/sessions/:id/share — update display_name / owner_label
+    // PATCH /api/v1/tasks/:id/share — update display_name / owner_label
     if (revokeMatch && method === "PATCH") {
         await handlePatchLabel(req, res, deps, decodeURIComponent(revokeMatch[1]));
         return true;
@@ -172,7 +172,7 @@ export async function handleShareRoutes(req, res, deps) {
         return true;
     }
     // Any other /api/v1/shares[/...] or /api/v1/shared/... miss → 404.
-    if (/^\/api\/v1\/sessions\/[^/]+\/share(?:\/|$|\?)/.test(url) ||
+    if (/^\/api\/v1\/tasks\/[^/]+\/share(?:\/|$|\?)/.test(url) ||
         url === "/api/v1/shares" ||
         url.startsWith("/api/v1/shares/") ||
         url.startsWith("/api/v1/shared/") ||
@@ -193,9 +193,9 @@ function resolveDisplayName(deps, validated) {
     return deps.store.getOwnerPref(DEFAULT_DISPLAY_NAME_KEY) ?? null;
 }
 /**
- * POST /api/v1/sessions/:id/share — create (or return existing) preview.
+ * POST /api/v1/tasks/:id/share — create (or return existing) preview.
  *
- * share-plan §4.2 R1-c1: same-session dedup — if an un-activated preview
+ * share-plan §4.2 R1-c1: same-task dedup — if an un-activated preview
  * already exists, return it verbatim. Only create new on miss.
  *
  * Body (all optional):
@@ -204,17 +204,17 @@ function resolveDisplayName(deps, validated) {
  *   display_name: str   — shown as "by @<name>" in viewer footer
  *   owner_label: str    — private owner-side label (full validation in C4)
  */
-async function handlePreviewCreate(req, res, deps, sessionId) {
-    const session = deps.store.getSession(sessionId);
-    if (!session) {
-        json(res, HTTP_STATUS.NOT_FOUND, { error: "session not found" });
+async function handlePreviewCreate(req, res, deps, taskId) {
+    const task = deps.store.getTask(taskId);
+    if (!task) {
+        json(res, HTTP_STATUS.NOT_FOUND, { error: "task not found" });
         return;
     }
-    // 409 guard: block while the agent is actively streaming into this session.
-    if (deps.sessions?.getBusyKind(sessionId) === "agent") {
+    // 409 guard: block while the agent is actively streaming into this task.
+    if (deps.tasks?.getBusyKind(taskId) === "agent") {
         json(res, HTTP_STATUS.CONFLICT, {
-            error: "session busy",
-            detail: "此 session 正在接收 agent 输出,请等 agent 输出结束后再分享",
+            error: "task busy",
+            detail: "此 task 正在接收 agent 输出,请等 agent 输出结束后再分享",
         });
         return;
     }
@@ -257,24 +257,24 @@ async function handlePreviewCreate(req, res, deps, sessionId) {
     const displayName = resolveDisplayName(deps, dnResult.value);
     const ownerLabel = olResult.value === "" ? null : olResult.value;
     try {
-        const existingInflight = pendingShareCreates.get(sessionId);
+        const existingInflight = pendingShareCreates.get(taskId);
         const inflight = existingInflight ??
             (async () => {
                 // Dedup first — existing preview short-circuits the gate.
-                const existing = deps.store.findActivePreviewBySession(sessionId);
+                const existing = deps.store.findActivePreviewByTask(taskId);
                 if (existing)
                     return { row: existing, reused: true };
                 // Flush buffered chunks so snapshot_seq includes the streaming tail.
-                deps.sessions?.flushBuffers(sessionId);
-                const allEvents = deps.store.getEvents(sessionId);
+                deps.tasks?.flushBuffers(taskId);
+                const allEvents = deps.store.getEvents(taskId);
                 const snapshotSeq = allEvents.length > 0 ? Math.max(...allEvents.map((e) => e.seq)) : 0;
                 // Gate: run the sanitizer on-write. Hard-rejects throw here so we
-                // never create a preview row for a session with leaked secrets.
-                runSanitizeGate(allEvents, session.cwd, deps.config.internal_hosts);
+                // never create a preview row for a task with leaked secrets.
+                runSanitizeGate(allEvents, task.cwd, deps.config.internal_hosts);
                 const token = generateShareToken();
                 const row = deps.store.insertSharePreview({
                     token,
-                    sessionId,
+                    taskId,
                     snapshotSeq,
                     ttlHours,
                     displayName,
@@ -282,14 +282,14 @@ async function handlePreviewCreate(req, res, deps, sessionId) {
                 });
                 return { row, reused: false };
             })().finally(() => {
-                pendingShareCreates.delete(sessionId);
+                pendingShareCreates.delete(taskId);
             });
         if (!existingInflight)
-            pendingShareCreates.set(sessionId, inflight);
+            pendingShareCreates.set(taskId, inflight);
         const result = await inflight;
         json(res, result.reused ? HTTP_STATUS.OK : HTTP_STATUS.CREATED, {
             token: result.row.token,
-            session_id: sessionId,
+            task_id: taskId,
             snapshot_seq: result.row.share_snapshot_seq,
             ttl_hours: result.row.ttl_hours,
             display_name: result.row.display_name,
@@ -326,14 +326,14 @@ function runSanitizeGate(events, cwd, internalHosts) {
     });
 }
 /**
- * GET /api/v1/sessions/:id/share/preview — read sanitized preview.
+ * GET /api/v1/tasks/:id/share/preview — read sanitized preview.
  *
  * Auth: owner + X-Share-Token header (token never in URL, never in logs).
  * Returns a `{schema_version, events, share}` bundle matching the public
  * viewer contract (minus public-only fields) so the overlay can share
  * the render path.
  */
-async function handlePreviewRead(req, res, deps, sessionId) {
+async function handlePreviewRead(req, res, deps, taskId) {
     const tokenHeader = req.headers["x-share-token"];
     const token = Array.isArray(tokenHeader) ? tokenHeader[0] : tokenHeader;
     if (!token) {
@@ -347,7 +347,7 @@ async function handlePreviewRead(req, res, deps, sessionId) {
         json(res, HTTP_STATUS.NOT_FOUND, { error: "share not found" });
         return;
     }
-    if (row.session_id !== sessionId) {
+    if (row.task_id !== taskId) {
         json(res, HTTP_STATUS.NOT_FOUND, { error: "share not found" });
         return;
     }
@@ -357,24 +357,24 @@ async function handlePreviewRead(req, res, deps, sessionId) {
         });
         return;
     }
-    const session = deps.store.getSession(sessionId);
-    if (!session) {
-        json(res, HTTP_STATUS.NOT_FOUND, { error: "session not found" });
+    const task = deps.store.getTask(taskId);
+    if (!task) {
+        json(res, HTTP_STATUS.NOT_FOUND, { error: "task not found" });
         return;
     }
     const allEvents = deps.store
-        .getEvents(sessionId)
+        .getEvents(taskId)
         .filter((e) => e.seq <= row.share_snapshot_seq);
-    if (deps.sessions) {
-        enrichStoredEventsForDisplay(allEvents, deps.sessions.getLabelMap(sessionId));
+    if (deps.tasks) {
+        enrichStoredEventsForDisplay(allEvents, deps.tasks.getLabelMap(taskId));
     }
     const currentLastSeq = deps.store
-        .getEvents(sessionId)
+        .getEvents(taskId)
         .reduce((m, e) => Math.max(m, e.seq), 0);
     try {
         const { events } = sanitizeEventsForShare({
             events: allEvents,
-            cwd: session.cwd,
+            cwd: task.cwd,
             homeDir: homedir(),
             internalHosts: deps.config.internal_hosts,
         });
@@ -384,8 +384,8 @@ async function handlePreviewRead(req, res, deps, sessionId) {
             schema_version: "1.0",
             share: {
                 token: row.token,
-                session_id: sessionId,
-                session_title: session.title,
+                task_id: taskId,
+                task_title: task.title,
                 shared_at: null,
                 snapshot_seq: row.share_snapshot_seq,
                 current_last_seq: currentLastSeq,
@@ -416,19 +416,19 @@ async function handlePreviewRead(req, res, deps, sessionId) {
     }
 }
 /**
- * POST /api/v1/sessions/:id/share/publish — activate an existing preview.
+ * POST /api/v1/tasks/:id/share/publish — activate an existing preview.
  *
  * Body: { token, display_name?, owner_label? }
- * - token MUST match a preview row for this session that has not been
+ * - token MUST match a preview row for this task that has not been
  *   activated or revoked.
  * - display_name / owner_label, if present, overwrite the preview row and
  *   are persisted into owner_prefs so the next /share defaults to them.
  *
- * Response: { token, session_id, shared_at, display_name, owner_label,
+ * Response: { token, task_id, shared_at, display_name, owner_label,
  *             public_url } on 200; 404/409/410 on state errors.
  */
 // eslint-disable-next-line complexity -- TODO: split validation / state-update / response phases
-async function handlePublish(req, res, deps, sessionId) {
+async function handlePublish(req, res, deps, taskId) {
     let body;
     try {
         body = (await readJson(req));
@@ -444,7 +444,7 @@ async function handlePublish(req, res, deps, sessionId) {
         json(res, HTTP_STATUS.BAD_REQUEST, { error: "token required" });
         return;
     }
-    if (!deps.store.ownsSession(sessionId)) {
+    if (!deps.store.ownsTask(taskId)) {
         json(res, HTTP_STATUS.NOT_FOUND, { error: "share not found" });
         return;
     }
@@ -453,7 +453,7 @@ async function handlePublish(req, res, deps, sessionId) {
         json(res, HTTP_STATUS.NOT_FOUND, { error: "share not found" });
         return;
     }
-    if (row.session_id !== sessionId) {
+    if (row.task_id !== taskId) {
         json(res, HTTP_STATUS.NOT_FOUND, { error: "share not found" });
         return;
     }
@@ -525,7 +525,7 @@ async function handlePublish(req, res, deps, sessionId) {
         : "";
     json(res, HTTP_STATUS.OK, {
         token: after.token,
-        session_id: sessionId,
+        task_id: taskId,
         shared_at: after.shared_at,
         display_name: after.display_name,
         owner_label: after.owner_label,
@@ -606,27 +606,27 @@ async function handleSharedEvents(res, deps, token) {
         return;
     }
     // Public viewer must keep working after the owner deletes the source
-    // session — events stay alive as long as any active share references
-    // them (Store.deleteSession soft-deletes when shares exist).
-    const session = deps.store.getSessionIncludingDeleted(row.session_id);
-    if (!session) {
-        json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, { error: "session vanished" });
+    // task — events stay alive as long as any active share references
+    // them (Store.deleteTask soft-deletes when shares exist).
+    const task = deps.store.getTaskIncludingDeleted(row.task_id);
+    if (!task) {
+        json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, { error: "task vanished" });
         return;
     }
     const allEvents = deps.store
-        .getEvents(row.session_id)
+        .getEvents(row.task_id)
         .filter((e) => e.seq <= row.share_snapshot_seq);
-    if (deps.sessions) {
-        enrichStoredEventsForDisplay(allEvents, deps.sessions.getLabelMap(row.session_id));
+    if (deps.tasks) {
+        enrichStoredEventsForDisplay(allEvents, deps.tasks.getLabelMap(row.task_id));
     }
     try {
         const { events } = sanitizeEventsForShare({
             events: allEvents,
-            cwd: session.cwd,
+            cwd: task.cwd,
             homeDir: homedir(),
             internalHosts: deps.config.internal_hosts,
         });
-        // Public response: DOES NOT expose session_id. Only title + display_name + meta.
+        // Public response: DOES NOT expose task_id. Only title + display_name + meta.
         res.writeHead(HTTP_STATUS.OK, {
             "Content-Type": "application/json",
             "Cache-Control": "no-store",
@@ -636,7 +636,7 @@ async function handleSharedEvents(res, deps, token) {
             schema_version: "1.0",
             share: {
                 token: row.token,
-                session_title: session.title,
+                task_title: task.title,
                 shared_at: row.shared_at,
                 snapshot_seq: row.share_snapshot_seq,
                 display_name: row.display_name,
@@ -648,7 +648,7 @@ async function handleSharedEvents(res, deps, token) {
     }
     catch (err) {
         if (err instanceof SanitizeError) {
-            // Hard-reject on a LIVE active share — owner's session gained a
+            // Hard-reject on a LIVE active share — owner's task gained a
             // post-publish leak. Return 410 publicly; owner sees root cause via
             // preview re-gate.
             slog.error("shared_events hard-reject", {
@@ -721,8 +721,8 @@ async function handleViewerAsset(res, deps, file) {
 }
 /**
  * GET /s/:token/attachments/:file — token-scoped image proxy. Resolves the token
- * to a session_id on-demand; directly serving /api/v1/sessions/:id/images
- * would leak session_id.
+ * to a task_id on-demand; directly serving /api/v1/tasks/:id/images
+ * would leak task_id.
  */
 async function handleViewerImage(res, deps, token, file) {
     if (!deps.dataDir) {
@@ -745,10 +745,10 @@ async function handleViewerImage(res, deps, token, file) {
         json(res, HTTP_STATUS.NOT_FOUND, { error: "invalid file" });
         return;
     }
-    const sessionRoot = join(deps.dataDir, "sessions", row.session_id, "attachments");
-    const filePath = join(sessionRoot, file);
-    // Final realpath-style guard: must stay under <dataDir>/sessions/<sid>/attachments.
-    if (!filePath.startsWith(sessionRoot + "/") && filePath !== sessionRoot) {
+    const taskRoot = join(deps.dataDir, "tasks", row.task_id, "attachments");
+    const filePath = join(taskRoot, file);
+    // Final realpath-style guard: must stay under <dataDir>/tasks/<sid>/attachments.
+    if (!filePath.startsWith(taskRoot + "/") && filePath !== taskRoot) {
         res.writeHead(HTTP_STATUS.FORBIDDEN);
         res.end("Forbidden");
         return;
@@ -760,7 +760,7 @@ async function handleViewerImage(res, deps, token, file) {
         // appends ".bin" to the <a download> name (e.g. zhihu.user.js →
         // zhihu.user.js.bin). The owner-side route at routes.ts does the
         // same lookup; share viewer needs parity for non-image attachments.
-        const att = deps.store.getAttachmentByFile(row.session_id, file);
+        const att = deps.store.getAttachmentByFile(row.task_id, file);
         const ext = extname(filePath).toLowerCase();
         let mime = att?.mime;
         mime ??= IMAGE_MIME[ext];
@@ -831,13 +831,13 @@ export function validateLabel(input, field, maxBytes = 1024) {
     return { ok: true, value: input };
 }
 /**
- * DELETE /api/v1/sessions/:id/share — revoke an active or preview share.
+ * DELETE /api/v1/tasks/:id/share — revoke an active or preview share.
  * Body: { token }.
  * Idempotent: already-revoked tokens return 200 with revoked=false.
  * Returns { ok, token, revoked, purge_status }. purge_status is always
  * 'skipped' in v1 — image/event purge is a future hardening pass.
  */
-async function handleRevoke(req, res, deps, sessionId) {
+async function handleRevoke(req, res, deps, taskId) {
     let body;
     try {
         body = (await readJson(req));
@@ -853,14 +853,14 @@ async function handleRevoke(req, res, deps, sessionId) {
         json(res, HTTP_STATUS.BAD_REQUEST, { error: "token required" });
         return;
     }
-    if (!deps.store.ownsSession(sessionId)) {
+    if (!deps.store.ownsTask(taskId)) {
         json(res, HTTP_STATUS.NOT_FOUND, { error: "share not found" });
         return;
     }
     const row = deps.store.getShareByToken(body.token);
     if (!row) {
         // Idempotent DELETE: row already gone (revoked or never existed).
-        // We can't verify session ownership without a row, but the token
+        // We can't verify task ownership without a row, but the token
         // is opaque/random so leaking "revoked or never existed" is fine.
         json(res, HTTP_STATUS.OK, {
             ok: true,
@@ -870,18 +870,18 @@ async function handleRevoke(req, res, deps, sessionId) {
         });
         return;
     }
-    if (row.session_id !== sessionId) {
+    if (row.task_id !== taskId) {
         json(res, HTTP_STATUS.NOT_FOUND, { error: "share not found" });
         return;
     }
     const revoked = deps.store.revokeShare(body.token);
-    // If this was the last share on a soft-deleted session, finish the
-    // hard-delete (events + sessions row) so we don't leak orphans.
+    // If this was the last share on a soft-deleted task, finish the
+    // hard-delete (events + tasks row) so we don't leak orphans.
     if (revoked) {
-        const reaped = deps.store.reapTombstoneIfOrphaned(row.session_id);
+        const reaped = deps.store.reapTombstoneIfOrphaned(row.task_id);
         if (reaped && deps.dataDir) {
-            // Tombstoned session is fully gone; sweep its attachments directory too.
-            rm(join(deps.dataDir, "sessions", row.session_id), {
+            // Tombstoned task is fully gone; sweep its attachments directory too.
+            rm(join(deps.dataDir, "tasks", row.task_id), {
                 recursive: true,
                 force: true,
             }).catch(() => { });
@@ -895,14 +895,14 @@ async function handleRevoke(req, res, deps, sessionId) {
     });
 }
 /**
- * PATCH /api/v1/sessions/:id/share — update owner_label / display_name on
+ * PATCH /api/v1/tasks/:id/share — update owner_label / display_name on
  * a live (non-revoked) share. Body: { token, owner_label?, display_name? }.
  *
  * Full validation: UTF-8 ≤1024B, no C0 controls (except TAB), no DEL, no
  * bidi overrides. Fields omitted from body are left unchanged; fields set
  * to empty string clear the value.
  */
-async function handlePatchLabel(req, res, deps, sessionId) {
+async function handlePatchLabel(req, res, deps, taskId) {
     let body;
     try {
         body = (await readJson(req));
@@ -918,7 +918,7 @@ async function handlePatchLabel(req, res, deps, sessionId) {
         json(res, HTTP_STATUS.BAD_REQUEST, { error: "token required" });
         return;
     }
-    if (!deps.store.ownsSession(sessionId)) {
+    if (!deps.store.ownsTask(taskId)) {
         json(res, HTTP_STATUS.NOT_FOUND, { error: "share not found" });
         return;
     }
@@ -927,7 +927,7 @@ async function handlePatchLabel(req, res, deps, sessionId) {
         json(res, HTTP_STATUS.NOT_FOUND, { error: "share not found" });
         return;
     }
-    if (row.session_id !== sessionId) {
+    if (row.task_id !== taskId) {
         json(res, HTTP_STATUS.NOT_FOUND, { error: "share not found" });
         return;
     }
@@ -962,7 +962,7 @@ async function handlePatchLabel(req, res, deps, sessionId) {
     }
     json(res, HTTP_STATUS.OK, {
         token: after.token,
-        session_id: sessionId,
+        task_id: taskId,
         owner_label: after.owner_label,
         display_name: after.display_name,
     });

package/lib/shared/task-reference.js

@@ -0,0 +1,20 @@
+/** Quote one task/path word for the shell-style task command grammar. */
+export function quoteShellWord(word) {
+    if (/[\s"'\\]/.test(word) || word === "") {
+        return `"${word.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    }
+    return word;
+}
+/** Format a task title as a stable, shell-parseable @ reference. */
+export function formatTaskReference(title) {
+    return `@${quoteShellWord(title)}`;
+}
+/**
+ * Format tree path segments as the absolute `@`-prefixed path the input grammar
+ * and the UI completion use. The caller decides which segments are root-relative
+ * (see `Store.getTaskPath`); this only renders them, shell-quoting as needed so
+ * the result can be pasted straight into the input.
+ */
+export function formatTaskPath(segments) {
+    return `@/${segments.map(quoteShellWord).join("/")}`;
+}