@harness-fe/mcp-server 3.4.1 → 4.0.0-next.1

package/dist/bridge.d.ts

@@ -12,7 +12,8 @@
  */
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import { type AuthOptions } from './auth.js';
-import { type EventFrame, type HttpBatch, type TabInfo, type Task, type TaskStatus } from '@harness-fe/protocol';
+import { type Principal } from './identity.js';
+import { type ConsentPolicy, type EventFrame, type HttpBatch, type TabInfo, type Task, type TaskStatus } from '@harness-fe/protocol';
 import { SessionRouter, type PeerSession } from './sessionRouter.js';
 import { type IStore, type ITaskStore, type IMemoryStore, type RetentionPolicy } from './store/index.js';
 /**
@@ -29,8 +30,8 @@ export interface IBridge {
         status?: TaskStatus | 'all';
         limit?: number;
     }): Promise<Task[]>;
-    claimTask(id: string): Promise<Task | undefined>;
-    resolveTask(id: string, note?: string): Promise<Task | undefined>;
+    claimTask(id: string, principal?: Principal): Promise<Task | undefined>;
+    resolveTask(id: string, note?: string, principal?: Principal): Promise<Task | undefined>;
     getMemoryStore(): IMemoryStore;
     /**
      * Base URL (e.g. http://127.0.0.1:47729) where the replay viewer is reachable.
@@ -75,6 +76,13 @@ export interface BridgeOptions {
      * token disables auth (only valid when bound to a loopback host).
      */
     auth?: AuthOptions;
+    /**
+     * Browser-consent policy for control commands (4.0 · P2). When omitted it
+     * defaults to `session` while auth is enabled (non-loopback / exposed) and
+     * `off` on loopback — so solo dev keeps its zero-friction flow and any
+     * exposed daemon prompts the user before an agent drives the page.
+     */
+    consent?: ConsentPolicy;
     /**
      * Override the host used when building outbound URLs (dashboard links,
      * replay viewer URLs). When omitted and `host` is `0.0.0.0` / `::`, the
@@ -157,6 +165,8 @@ export declare class Bridge implements IBridge {
     private tasks;
     private opts;
     private auth;
+    /** Browser-consent policy pushed to runtime clients in hello.ack (4.0 · P2). */
+    private readonly consentPolicy;
     private publicHostOverride;
     private readonly attachDataDir;
     private autoPurgeOpts;
@@ -167,6 +177,15 @@ export declare class Bridge implements IBridge {
      * or sessionId (for runtime-client connections).
      */
     private connToStoreId;
+    /** Caller identity per connection (4.0 · P1). Resolved at WS upgrade. */
+    private connToPrincipal;
+    /**
+     * Identity attributed to MCP-driven writes (task claim/resolve). The MCP
+     * tool layer is a daemon-wide singleton today with no per-call caller
+     * context, so stdio/HTTP agents collapse to one principal. P4 (per-session
+     * MCP transport) replaces this with the real per-call principal.
+     */
+    private readonly defaultPrincipal;
     /** Connections that already logged a "no store session" warning. */
     private warnedNoSession;
     /**
@@ -228,6 +247,8 @@ export declare class Bridge implements IBridge {
     getBoundPort(): number | undefined;
     getViewerBaseUrl(): string | undefined;
     getAuthToken(): string | undefined;
+    /** Daemon auth options — used by the MCP layer to identify the per-call principal (4.0 · P4). */
+    getAuthOptions(): AuthOptions;
     /**
      * Broadcast a `dashboard.update` frame to every subscribed dashboard SPA.
      *
@@ -264,9 +285,9 @@ export declare class Bridge implements IBridge {
         status?: TaskStatus | 'all';
         limit?: number;
     }): Promise<Task[]>;
-    claimTask(id: string): Promise<Task | undefined>;
+    claimTask(id: string, principal?: Principal): Promise<Task | undefined>;
     getTaskAttachmentData(taskId: string, attachmentId: string): Promise<string | null>;
-    resolveTask(id: string, note?: string): Promise<Task | undefined>;
+    resolveTask(id: string, note?: string, principal?: Principal): Promise<Task | undefined>;
     private persistTaskEvent;
     private recordTask;
     /**

package/dist/bridge.js

@@ -14,7 +14,8 @@ import { WebSocket, WebSocketServer } from 'ws';
 import { randomUUID } from 'node:crypto';
 import { createServer } from 'node:http';
 import { networkInterfaces } from 'node:os';
-import { DEFAULT_LOGIN_PATH, handleLoginPost, isAuthorized, sendUnauthorized, } from './auth.js';
+import { DEFAULT_LOGIN_PATH, handleLoginPost, isAuthEnabled, isAuthorized, sendUnauthorized, } from './auth.js';
+import { LOCAL_PRINCIPAL, resolvePrincipal } from './identity.js';
 import { join as joinPath } from 'node:path';
 import { homedir } from 'node:os';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -59,6 +60,8 @@ export class Bridge {
     tasks = new Map();
     opts;
     auth;
+    /** Browser-consent policy pushed to runtime clients in hello.ack (4.0 · P2). */
+    consentPolicy;
     publicHostOverride;
     attachDataDir;
     autoPurgeOpts;
@@ -69,6 +72,15 @@ export class Bridge {
      * or sessionId (for runtime-client connections).
      */
     connToStoreId = new Map();
+    /** Caller identity per connection (4.0 · P1). Resolved at WS upgrade. */
+    connToPrincipal = new Map();
+    /**
+     * Identity attributed to MCP-driven writes (task claim/resolve). The MCP
+     * tool layer is a daemon-wide singleton today with no per-call caller
+     * context, so stdio/HTTP agents collapse to one principal. P4 (per-session
+     * MCP transport) replaces this with the real per-call principal.
+     */
+    defaultPrincipal = LOCAL_PRINCIPAL;
     /** Connections that already logged a "no store session" warning. */
     warnedNoSession = new Set();
     /**
@@ -107,6 +119,12 @@ export class Bridge {
             host: opts.host ?? '127.0.0.1',
         };
         this.auth = opts.auth ?? {};
+        // Consent defaults track the auth boundary: exposed (auth on) ⇒ prompt
+        // once per session; loopback solo (auth off) ⇒ no prompts. Explicit
+        // opts.consent always wins.
+        this.consentPolicy = opts.consent ?? {
+            mode: isAuthEnabled(this.auth) ? 'session' : 'off',
+        };
         this.publicHostOverride = opts.publicHost;
         // Default auto-purge ON. CI / tests pass `enabled: false` (or set
         // env HARNESS_FE_PURGE_DISABLED=1) to opt out.
@@ -272,7 +290,7 @@ export class Bridge {
                 res.end('Not Found');
             });
             const wss = new WebSocketServer({ noServer: true });
-            wss.on('connection', (ws) => this.onConnection(ws));
+            wss.on('connection', (ws, req) => this.onConnection(ws, req));
             httpServer.on('upgrade', (req, socket, head) => {
                 if (!isAuthorized(req, this.auth)) {
                     // Spec-compliant 401 on the upgrade reply so client sees a
@@ -379,6 +397,10 @@ export class Bridge {
     getAuthToken() {
         return this.auth.token;
     }
+    /** Daemon auth options — used by the MCP layer to identify the per-call principal (4.0 · P4). */
+    getAuthOptions() {
+        return this.auth;
+    }
     /**
      * Broadcast a `dashboard.update` frame to every subscribed dashboard SPA.
      *
@@ -539,12 +561,16 @@ export class Bridge {
         filtered.sort((a, b) => b.createdAt - a.createdAt);
         return filtered.slice(0, limit);
     }
-    async claimTask(id) {
+    async claimTask(id, principal) {
         const task = this.tasks.get(id);
         if (!task)
             return undefined;
         task.status = 'claimed';
         task.claimedAt = Date.now();
+        // Tag which agent picked it up (4.0 · P1/P4). The per-call principal
+        // (HTTP MCP, resolved from request headers) wins; stdio / no-caller
+        // falls back to the daemon's local principal.
+        task.agentId = (principal ?? this.defaultPrincipal).id;
         this.persistTasks();
         // Persist status change to store
         this.persistTaskEvent(task, 'task:claim');
@@ -556,7 +582,7 @@ export class Bridge {
             return null;
         return this.readTaskAttachment(task.projectId, taskId, attachmentId);
     }
-    async resolveTask(id, note) {
+    async resolveTask(id, note, principal) {
         const task = this.tasks.get(id);
         if (!task)
             return undefined;
@@ -564,6 +590,8 @@ export class Bridge {
         task.resolvedAt = Date.now();
         if (note !== undefined)
             task.note = note;
+        if (!task.agentId)
+            task.agentId = (principal ?? this.defaultPrincipal).id;
         this.persistTasks();
         // Persist status change to store
         this.persistTaskEvent(task, 'task:resolve');
@@ -818,9 +846,13 @@ export class Bridge {
         }
         return false;
     }
-    onConnection(ws) {
+    onConnection(ws, req) {
         const connectionId = randomUUID();
         this.sockets.set(connectionId, ws);
+        // Resolve caller identity once at connection time (4.0 · P1). The
+        // upgrade handler already enforced isAuthorized, so resolvePrincipal
+        // won't reject here; fall back to LOCAL for the loopback / no-req path.
+        this.connToPrincipal.set(connectionId, (req && resolvePrincipal(req, this.auth)) || LOCAL_PRINCIPAL);
         ws.on('message', (raw) => {
             let parsed;
             try {
@@ -880,6 +912,7 @@ export class Bridge {
                 }
             }
             this.router.unregister(connectionId);
+            this.connToPrincipal.delete(connectionId);
         });
         ws.on('error', () => {
             /* swallow; close will follow */
@@ -924,6 +957,7 @@ export class Bridge {
                 // production / staging deployment where the bundler plugin is
                 // absent. The runtime-client branch below opens its own store
                 // session if one does not already exist for this project.
+                const principal = this.connToPrincipal.get(connectionId) ?? LOCAL_PRINCIPAL;
                 const session = this.router.register({
                     role: frame.role,
                     projectId: frame.projectId,
@@ -933,6 +967,7 @@ export class Bridge {
                     userId: frame.userId,
                     connectionId,
                     page: frame.page,
+                    principal,
                 });
                 // Persist to store
                 if (this.store) {
@@ -944,6 +979,7 @@ export class Bridge {
                             this.store.upsertProject(frame.projectId, {
                                 parentProjectId: frame.parentProjectId,
                                 displayName: frame.displayName,
+                                createdBy: principal.id,
                             });
                         }
                         catch (err) {
@@ -1018,6 +1054,7 @@ export class Bridge {
                             referrer: undefined,
                             userAgent: frame.page?.userAgent,
                             participants,
+                            createdBy: principal.id,
                         });
                         this.connToStoreId.set(connectionId, sessionId);
                         this.notifyDashboard({
@@ -1060,6 +1097,7 @@ export class Bridge {
                     id: frame.id,
                     tabId: session.tabId,
                     serverVersion: PROTOCOL_VERSION,
+                    consent: this.consentPolicy,
                 };
                 ws.send(JSON.stringify(ack));
                 // One concise line per accepted peer. Visibility for "is the

package/dist/daemon.d.ts

@@ -23,6 +23,7 @@
  * not pushed into the factory.
  */
 import type { IncomingMessage } from 'node:http';
+import type { ConsentPolicy } from '@harness-fe/protocol';
 import { Bridge } from './bridge.js';
 import type { EventStore, IStore } from './store/types.js';
 import type { ITaskStore, IMemoryStore } from './store/types.js';
@@ -56,6 +57,12 @@ export interface DaemonOptions {
      * flows through here. Mutually exclusive with `authorize`.
      */
     token?: string;
+    /**
+     * Browser-consent policy for control commands (4.0 · P2). Omit to track the
+     * auth boundary automatically: `session` when auth is on (exposed daemon),
+     * `off` on loopback solo dev. Pass `{ mode }` to force a policy.
+     */
+    consent?: ConsentPolicy;
     /**
      * IStore implementation. Omit for the default JSONL store at `dataDir`.
      * Pass `null` to disable session/event persistence entirely.

package/dist/daemon.js

@@ -45,6 +45,7 @@ export function createDaemon(opts = {}) {
         dataDir: opts.dataDir,
         label: opts.label,
         auth,
+        consent: opts.consent,
     });
     let mcpHandle;
     let started = false;

package/dist/identity.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Caller identity (4.0 · P1) — turns the auth boundary from a plain
+ * allow/deny into "allow/deny + *who*".
+ *
+ * Phase 1 scope: this module only *establishes* and *carries* a Principal,
+ * and the bridge *tags* writes with it (createdBy). It deliberately does NOT
+ * filter reads by owner — that's P3 (tenant isolation). Keeping the two apart
+ * means identity plumbing lands with zero behaviour change: loopback solo dev
+ * stays a single implicit `local` principal, and an authorized caller sees
+ * everything exactly as before.
+ *
+ * Why a separate module from auth.ts: `isAuthorized` answers a boolean and is
+ * consumed on the hot path of every HTTP route / WS upgrade. `resolvePrincipal`
+ * is the richer, additive view layered on top — it reuses the same primitives
+ * (isAuthEnabled / extractToken / verifyToken) so the two can never disagree on
+ * who is allowed in.
+ */
+import type { IncomingMessage } from 'node:http';
+import { type AuthOptions } from './auth.js';
+export type PrincipalKind = 'local' | 'token' | 'host';
+export interface Principal {
+    /** Stable id for this caller. Loopback / stdio solo dev → `local`. */
+    id: string;
+    /** How the identity was established. */
+    kind: PrincipalKind;
+    /** Optional human-readable label (for dashboards / audit). */
+    displayName?: string;
+}
+/**
+ * The implicit single principal for loopback and stdio solo dev. The daemon
+ * trusts everything that can reach the loopback socket, so there is one
+ * caller and it owns everything — exactly today's behaviour, now named.
+ */
+export declare const LOCAL_PRINCIPAL: Principal;
+/**
+ * Principal for the custom-`authorize` path. Hosts that embed the daemon own
+ * their own user model; until `authorize` can return a richer identity
+ * (future work), an authorized host caller maps to this single principal.
+ */
+export declare const HOST_PRINCIPAL: Principal;
+/**
+ * Derive a stable principal id from a bearer token. One token = one principal
+ * in 4.0's trusted-team model. We hash so the raw secret never becomes an id
+ * that could leak into stored `createdBy` tags or audit logs.
+ */
+export declare function tokenPrincipalId(token: string): string;
+/**
+ * Resolve the caller behind a request.
+ *
+ * Returns `null` when auth is enabled and the request is NOT authorized — this
+ * mirrors `isAuthorized(req) === false` exactly, so callers can treat a null
+ * principal as "reject" without a second auth check.
+ *
+ * - auth disabled (loopback): {@link LOCAL_PRINCIPAL}
+ * - custom `authorize`: {@link HOST_PRINCIPAL} when it accepts, else `null`
+ * - token: a {@link tokenPrincipalId}-derived principal when it matches, else `null`
+ */
+export declare function resolvePrincipal(req: IncomingMessage, opts: AuthOptions): Principal | null;
+type HeaderBag = Record<string, string | string[] | undefined>;
+/**
+ * Identify (not authorize) the caller behind an MCP tool call (4.0 · P4).
+ *
+ * The HTTP MCP request has already cleared the bridge's auth wrapper by the
+ * time a tool runs, so this only needs to *name* the caller — never to
+ * re-check them. Pass the per-request headers from the MCP SDK's
+ * `extra.requestInfo`; stdio calls have no requestInfo and resolve to `local`
+ * (the daemon trusts its local stdio agent).
+ *
+ * - auth disabled, or no headers (stdio) → {@link LOCAL_PRINCIPAL}
+ * - custom authorize → {@link HOST_PRINCIPAL}
+ * - token mode → token principal from the Authorization header (LOCAL if absent)
+ */
+export declare function identifyPrincipal(headers: HeaderBag | undefined, opts: AuthOptions): Principal;
+export {};

package/dist/identity.js

@@ -0,0 +1,101 @@
+/**
+ * Caller identity (4.0 · P1) — turns the auth boundary from a plain
+ * allow/deny into "allow/deny + *who*".
+ *
+ * Phase 1 scope: this module only *establishes* and *carries* a Principal,
+ * and the bridge *tags* writes with it (createdBy). It deliberately does NOT
+ * filter reads by owner — that's P3 (tenant isolation). Keeping the two apart
+ * means identity plumbing lands with zero behaviour change: loopback solo dev
+ * stays a single implicit `local` principal, and an authorized caller sees
+ * everything exactly as before.
+ *
+ * Why a separate module from auth.ts: `isAuthorized` answers a boolean and is
+ * consumed on the hot path of every HTTP route / WS upgrade. `resolvePrincipal`
+ * is the richer, additive view layered on top — it reuses the same primitives
+ * (isAuthEnabled / extractToken / verifyToken) so the two can never disagree on
+ * who is allowed in.
+ */
+import { createHash } from 'node:crypto';
+import { extractToken, isAuthEnabled, verifyToken } from './auth.js';
+/**
+ * The implicit single principal for loopback and stdio solo dev. The daemon
+ * trusts everything that can reach the loopback socket, so there is one
+ * caller and it owns everything — exactly today's behaviour, now named.
+ */
+export const LOCAL_PRINCIPAL = Object.freeze({
+    id: 'local',
+    kind: 'local',
+    displayName: 'local',
+});
+/**
+ * Principal for the custom-`authorize` path. Hosts that embed the daemon own
+ * their own user model; until `authorize` can return a richer identity
+ * (future work), an authorized host caller maps to this single principal.
+ */
+export const HOST_PRINCIPAL = Object.freeze({
+    id: 'host',
+    kind: 'host',
+    displayName: 'host',
+});
+/**
+ * Derive a stable principal id from a bearer token. One token = one principal
+ * in 4.0's trusted-team model. We hash so the raw secret never becomes an id
+ * that could leak into stored `createdBy` tags or audit logs.
+ */
+export function tokenPrincipalId(token) {
+    return `token:${createHash('sha256').update(token).digest('hex').slice(0, 12)}`;
+}
+/**
+ * Resolve the caller behind a request.
+ *
+ * Returns `null` when auth is enabled and the request is NOT authorized — this
+ * mirrors `isAuthorized(req) === false` exactly, so callers can treat a null
+ * principal as "reject" without a second auth check.
+ *
+ * - auth disabled (loopback): {@link LOCAL_PRINCIPAL}
+ * - custom `authorize`: {@link HOST_PRINCIPAL} when it accepts, else `null`
+ * - token: a {@link tokenPrincipalId}-derived principal when it matches, else `null`
+ */
+export function resolvePrincipal(req, opts) {
+    if (!isAuthEnabled(opts))
+        return LOCAL_PRINCIPAL;
+    if (opts.authorize)
+        return opts.authorize(req) ? HOST_PRINCIPAL : null;
+    const token = extractToken(req, opts);
+    if (!verifyToken(token, opts.token))
+        return null;
+    return { id: tokenPrincipalId(token), kind: 'token' };
+}
+function bearerFromHeaders(headers) {
+    const raw = headers['authorization'] ?? headers['Authorization'];
+    const v = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof v === 'string' && v.startsWith('Bearer ')) {
+        const t = v.slice(7).trim();
+        if (t)
+            return t;
+    }
+    return undefined;
+}
+/**
+ * Identify (not authorize) the caller behind an MCP tool call (4.0 · P4).
+ *
+ * The HTTP MCP request has already cleared the bridge's auth wrapper by the
+ * time a tool runs, so this only needs to *name* the caller — never to
+ * re-check them. Pass the per-request headers from the MCP SDK's
+ * `extra.requestInfo`; stdio calls have no requestInfo and resolve to `local`
+ * (the daemon trusts its local stdio agent).
+ *
+ * - auth disabled, or no headers (stdio) → {@link LOCAL_PRINCIPAL}
+ * - custom authorize → {@link HOST_PRINCIPAL}
+ * - token mode → token principal from the Authorization header (LOCAL if absent)
+ */
+export function identifyPrincipal(headers, opts) {
+    if (!isAuthEnabled(opts))
+        return LOCAL_PRINCIPAL;
+    if (opts.authorize)
+        return HOST_PRINCIPAL;
+    if (!headers)
+        return LOCAL_PRINCIPAL;
+    const token = bearerFromHeaders(headers);
+    return token ? { id: tokenPrincipalId(token), kind: 'token' } : LOCAL_PRINCIPAL;
+}

package/dist/mcp.d.ts

@@ -7,6 +7,7 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { IBridge } from './bridge.js';
+import type { AuthOptions } from './auth.js';
 export interface McpServerOptions {
     /**
      * Name of the environment variable that gates experimental tools.
@@ -17,6 +18,12 @@ export interface McpServerOptions {
      * var is set to a non-empty value at server-construction time.
      */
     experimentalEnvVar?: string;
+    /**
+     * Daemon auth options, used to identify the per-call principal from MCP
+     * request headers (4.0 · P4). Omit for stdio / no-auth — calls resolve to
+     * the local principal.
+     */
+    auth?: AuthOptions;
 }
 /**
  * Experimental-feature gate.

package/dist/mcp.js

@@ -9,6 +9,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { COMMAND, PROTOCOL_VERSION, clickArgsSchema, evaluateArgsSchema, navigateArgsSchema, reloadArgsSchema, screenshotArgsSchema, scrollArgsSchema, setHtmlArgsSchema, setStyleArgsSchema, selectorSchema, typeArgsSchema, waitForArgsSchema, } from '@harness-fe/protocol';
+import { identifyPrincipal } from './identity.js';
 import { RemoteBridge } from './remoteBridge.js';
 import { buildVisitorTimeline } from './visitorTimeline.js';
 import { createReplayExport } from './replayCreate.js';
@@ -47,7 +48,7 @@ export function createMcpServer(bridge, options = {}) {
         name: SERVER_NAME,
         version: PROTOCOL_VERSION,
     });
-    registerTools(server, bridge);
+    registerTools(server, bridge, options.auth);
     // Experimental tools are on by default. They only get gated when the host
     // supplies an env-var name to key off; see experimentalEnabled().
     if (experimentalEnabled(options.experimentalEnvVar)) {
@@ -87,7 +88,7 @@ function err(message) {
         isError: true,
     };
 }
-function registerTools(server, bridge) {
+function registerTools(server, bridge, auth) {
     server.registerTool(COMMAND.PAGE_CLICK, {
         description: 'Click on a DOM element resolved by the selector.',
         inputSchema: {
@@ -452,83 +453,79 @@ function registerTools(server, bridge) {
         return ok(out);
     });
     // ─── tasks.* tools (user annotations submitted from page) ─────────────
-    // TODO: temporarily hidden — re-enable when the report feature is ready.
-    // To re-enable: remove the `if (false)` wrapper below and restore the block.
-    /* eslint-disable no-constant-condition */
-    if (false) {
-        const taskStatusEnum = z.enum(['pending', 'claimed', 'resolved', 'all']);
-        server.registerTool(COMMAND.TASKS_PENDING, {
-            description: 'List user-submitted annotation tasks. Default `status="pending"`. Returns id/question/selector/url — call tasks.claim to fetch full element payload.',
-            inputSchema: {
-                status: taskStatusEnum.optional(),
-                limit: z.number().int().positive().optional(),
-            },
-        }, async ({ status, limit }) => {
-            const tasks = await bridge.listTasks({ status: status ?? 'pending', limit });
-            const summary = tasks.map((t) => ({
-                id: t.id,
-                status: t.status,
-                question: t.question,
-                selector: t.selector,
-                url: t.url,
-                tabId: t.tabId,
-                createdAt: t.createdAt,
-                claimedAt: t.claimedAt,
-                resolvedAt: t.resolvedAt,
-                note: t.note,
-            }));
-            return ok({ count: summary.length, tasks: summary });
-        });
-        server.registerTool(COMMAND.TASKS_CLAIM, {
-            description: 'Claim a task by id. Marks it claimed, returns full payload (selector + element outerHTML + rect).',
-            inputSchema: {
-                taskId: z.string(),
-            },
-        }, async ({ taskId }) => {
-            const task = await bridge.claimTask(taskId);
-            if (!task) {
-                throw new Error(`tasks.claim: no task with id "${taskId}"`);
-            }
-            return ok(task);
-        });
-        server.registerTool(COMMAND.TASKS_RESOLVE, {
-            description: 'Mark a task as resolved with an optional note. Use after addressing the user request.',
-            inputSchema: {
-                taskId: z.string(),
-                note: z.string().optional(),
-            },
-        }, async ({ taskId, note }) => {
-            const task = await bridge.resolveTask(taskId, note);
-            if (!task) {
-                throw new Error(`tasks.resolve: no task with id "${taskId}"`);
-            }
-            return ok({ ok: true, task });
-        });
-        server.registerTool('tasks.get_attachment', {
-            description: 'Return a task screenshot attachment as a vision-ready image block. ' +
-                'Call after tasks.claim when the task summary includes an attachment pointer. ' +
-                'Compatible with Claude vision and GPT-4V.',
-            inputSchema: {
-                taskId: z.string().describe('Task id (from tasks.pending or tasks.claim).'),
-                attachmentId: z.string().describe('Attachment id (from task.attachments[].id).'),
-            },
-        }, async ({ taskId, attachmentId }) => {
-            const base64 = await bridge.getTaskAttachmentData(taskId, attachmentId);
-            if (!base64) {
-                throw new Error(`tasks.get_attachment: attachment not found (taskId=${taskId}, attachmentId=${attachmentId})`);
-            }
-            return {
-                content: [
-                    {
-                        type: 'image',
-                        mimeType: 'image/png',
-                        data: base64,
-                    },
-                ],
-            };
-        });
-    }
-    /* eslint-enable no-constant-condition */
+    const taskStatusEnum = z.enum(['pending', 'claimed', 'resolved', 'all']);
+    server.registerTool(COMMAND.TASKS_PENDING, {
+        description: 'List user-submitted annotation tasks. Default `status="pending"`. Returns id/question/selector/url — call tasks.claim to fetch full element payload.',
+        inputSchema: {
+            status: taskStatusEnum.optional(),
+            limit: z.number().int().positive().optional(),
+        },
+    }, async ({ status, limit }) => {
+        const tasks = await bridge.listTasks({ status: status ?? 'pending', limit });
+        const summary = tasks.map((t) => ({
+            id: t.id,
+            status: t.status,
+            question: t.question,
+            selector: t.selector,
+            url: t.url,
+            tabId: t.tabId,
+            createdAt: t.createdAt,
+            claimedAt: t.claimedAt,
+            resolvedAt: t.resolvedAt,
+            note: t.note,
+        }));
+        return ok({ count: summary.length, tasks: summary });
+    });
+    server.registerTool(COMMAND.TASKS_CLAIM, {
+        description: 'Claim a task by id. Marks it claimed, returns full payload (selector + element outerHTML + rect).',
+        inputSchema: {
+            taskId: z.string(),
+        },
+    }, async ({ taskId }, extra) => {
+        const principal = identifyPrincipal(extra.requestInfo?.headers, auth ?? {});
+        const task = await bridge.claimTask(taskId, principal);
+        if (!task) {
+            throw new Error(`tasks.claim: no task with id "${taskId}"`);
+        }
+        return ok(task);
+    });
+    server.registerTool(COMMAND.TASKS_RESOLVE, {
+        description: 'Mark a task as resolved with an optional note. Use after addressing the user request.',
+        inputSchema: {
+            taskId: z.string(),
+            note: z.string().optional(),
+        },
+    }, async ({ taskId, note }, extra) => {
+        const principal = identifyPrincipal(extra.requestInfo?.headers, auth ?? {});
+        const task = await bridge.resolveTask(taskId, note, principal);
+        if (!task) {
+            throw new Error(`tasks.resolve: no task with id "${taskId}"`);
+        }
+        return ok({ ok: true, task });
+    });
+    server.registerTool('tasks.get_attachment', {
+        description: 'Return a task screenshot attachment as a vision-ready image block. ' +
+            'Call after tasks.claim when the task summary includes an attachment pointer. ' +
+            'Compatible with Claude vision and GPT-4V.',
+        inputSchema: {
+            taskId: z.string().describe('Task id (from tasks.pending or tasks.claim).'),
+            attachmentId: z.string().describe('Attachment id (from task.attachments[].id).'),
+        },
+    }, async ({ taskId, attachmentId }) => {
+        const base64 = await bridge.getTaskAttachmentData(taskId, attachmentId);
+        if (!base64) {
+            throw new Error(`tasks.get_attachment: attachment not found (taskId=${taskId}, attachmentId=${attachmentId})`);
+        }
+        return {
+            content: [
+                {
+                    type: 'image',
+                    mimeType: 'image/png',
+                    data: base64,
+                },
+            ],
+        };
+    });
 }
 // ─── Experimental tools (gated by HARNESS_FE_EXPERIMENTAL) ────────────────────
 /**