chore(server): fix lint errors in cli, organize imports; build server

Author: yayasoumah

README.md

@@ -75,6 +75,38 @@ Flags
   --pin <code>          Override generated PIN (pair only)
 ```
 
+Terminal commands (resume sessions on desktop)
+----------------------------------------------
+
+Pocket Server can attach your mobile terminal sessions on your desktop terminal. No pairing or token is required on your own machine — the CLI and server exchange a local secret under `~/.pocket-server/data/runtime/local-ws.key`.
+
+```
+# List active terminal sessions with indices
+pocket-server terminal sessions
+
+# Attach by index (from the list)
+pocket-server terminal attach 2
+
+# Attach by title (case-insensitive, supports spaces)
+pocket-server terminal attach --name "Opencode"
+# or positional query
+pocket-server terminal attach "Opencode"
+
+# Attach by id
+pocket-server terminal attach --id term:/path#3
+
+# JSON output for tooling
+pocket-server terminal sessions --json
+
+# Optional: specify a port if not 3000
+pocket-server terminal attach 1 --port 3010
+```
+
+Notes
+- Attach streams the session interactively into your current terminal. Press Ctrl+C to detach without closing the remote PTY.
+- The desktop attach replays terminal output to reconstruct the TUI exactly as you left it on mobile. It does not clear your local terminal.
+- Session titles come from the mobile tabs; you can long‑press to rename on mobile and they’ll appear here.
+
 How Pocket works (high level)
 -----------------------------
 

src/agent/anthropic/anthropic.ts

@@ -10,6 +10,7 @@ import { generateTitle } from './title';
 import { bashToolDefinition, executeBash } from './tools/bash';
 import { editorToolDefinition, executeEditor } from './tools/editor';
 import { executeWebSearch, webSearchToolDefinition } from './tools/web-search';
+import { executeWorkPlan, workPlanToolDefinition } from './tools/work-plan';
 import type { 
   AgentSession, 
   ClientMessage, 
@@ -63,7 +64,7 @@ export class AnthropicService {
           },
           settings: {
             maxTokens: 4096,
-            tools: [bashToolDefinition, editorToolDefinition, webSearchToolDefinition]
+            tools: [bashToolDefinition, editorToolDefinition, webSearchToolDefinition, workPlanToolDefinition]
           }
         },
         streamingState: {
@@ -137,7 +138,7 @@ export class AnthropicService {
     const systemPrompt = generateSystemPrompt({ workingDirectory: workingDir });
 
     // Prepare tools
-    const tools = [bashToolDefinition, editorToolDefinition, webSearchToolDefinition];
+    const tools = [bashToolDefinition, editorToolDefinition, webSearchToolDefinition, workPlanToolDefinition];
 
     try {
       // Store reference to current stream for potential cancellation
@@ -239,6 +240,10 @@ export class AnthropicService {
                 output = await executeWebSearch(req.input, workingDir);
                 isError = false;
                 break;
+              case 'work_plan':
+                output = await executeWorkPlan(sessionId, req.input);
+                isError = false;
+                break;
               default:
                 output = `Unknown tool: ${req.name}`;
                 isError = true;
@@ -386,6 +391,10 @@ export class AnthropicService {
             result = await executeWebSearch(toolUse.input, session.workingDir);
             isError = false;
             break;
+          case 'work_plan':
+            result = await executeWorkPlan(session.id, toolUse.input);
+            isError = false;
+            break;
           default:
             result = `Unknown tool: ${toolUse.name}`;
             isError = true;
@@ -484,7 +493,7 @@ export class AnthropicService {
     onMessage: (msg: ServerMessage) => void
   ): Promise<void> {
     const systemPrompt = generateSystemPrompt({ workingDirectory: session.workingDir });
-    const tools = [bashToolDefinition, editorToolDefinition, webSearchToolDefinition];
+    const tools = [bashToolDefinition, editorToolDefinition, webSearchToolDefinition, workPlanToolDefinition];
 
     try {
       // Store reference to current stream for potential cancellation  
@@ -566,6 +575,10 @@ export class AnthropicService {
                 output = await executeWebSearch(req.input, session.workingDir);
                 isError = false;
                 break;
+              case 'work_plan':
+                output = await executeWorkPlan(session.id, req.input);
+                isError = false;
+                break;
               default:
                 output = `Unknown tool: ${req.name}`;
                 isError = true;
@@ -753,4 +766,4 @@ export class AnthropicService {
 }
 
 // Export singleton instance
-export const anthropicService = new AnthropicService();
+export const anthropicService = new AnthropicService();

src/agent/anthropic/prompt.ts

@@ -68,6 +68,17 @@ Search the web for current information:
 - Up to 5 searches per request
 - Results include page titles, URLs, and content
 
+### 4. Work Plan Tool (work_plan)
+Use a structured to-do for multi-step tasks:
+- **create**: Declare an ordered list of steps with short titles; include \`estimated_seconds\` when possible.
+- **complete**: Mark a step as done by id when you finish it.
+- **revise**: Adjust titles, order, or add/remove items if your plan changes.
+
+Guidelines:
+- Only create a plan for genuinely multi-step requests. For a simple greeting or single-step ask, skip the plan.
+- Keep step titles short and mobile-friendly (<= 80 chars).
+- When a step is finished, call \`complete\` immediately so the user receives a push about the next step.
+
 ## Operating Modes
 
 ### Standard Mode
@@ -104,4 +115,4 @@ When enabled by the user:
    - Consider error handling and edge cases
 
 Remember: You're helping users code effectively from their mobile devices, making development accessible anywhere.`;
-}
+}

src/agent/anthropic/streaming.ts

@@ -192,7 +192,8 @@ export async function processStream(
 
                 // For Max (chatMode === false) auto-approval: queue tool requests to execute AFTER this stream completes,
                 // so we can send them back to the API in the required "user tool_result" message format.
-                if (!chatMode && isToolSafe(toolRequest)) {
+                // Auto-approve safe tools in Max mode, and always auto-approve work_plan
+                if ((!chatMode && isToolSafe(toolRequest)) || toolRequest.name === 'work_plan') {
                   state.autoToolRequests?.push(toolRequest);
                 } else {
                   // Chat mode: send to client for manual approval
@@ -335,6 +336,8 @@ function isToolSafe(request: ToolRequest): boolean {
       return !isEditorCommandDangerous(request.input);
     case 'web_search':
       return true; // Web search is always safe
+    case 'work_plan':
+      return true; // Server-local plan state; safe
     default:
       return false;
   }
@@ -365,7 +368,17 @@ function generateToolDescription(toolName: string, input: any): string {
     }
   } else if (toolName === 'web_search' && input?.query) {
     return `Search: ${input.query}`;
+  } else if (toolName === 'work_plan') {
+    if (input?.command === 'create' && Array.isArray(input?.items)) {
+      return `Create work plan: ${input.items.length} steps`;
+    }
+    if (input?.command === 'complete') {
+      return `Complete step ${input.id}`;
+    }
+    if (input?.command === 'revise') {
+      return `Revise work plan (${(input.items || []).length} changes)`;
+    }
   }
 
   return 'Execute tool';
-}
+}

src/agent/anthropic/tools/work-plan.ts

@@ -0,0 +1,87 @@
+/**
+ * Work Plan Tool
+ * Lets the model declare a multi-step plan and mark steps complete.
+ * We persist plan state in the session snapshot and emit targeted push notifications
+ * via the existing Expo notifications pipeline.
+ */
+
+import { notificationsService } from '../../../notifications/index';
+import { getInitiatorDeviceId } from '../../session-initiators';
+import { sessionStoreFs } from '../../store/session-store-fs';
+import type { WorkPlanCommand, WorkPlanTool } from '../types';
+
+export const workPlanToolDefinition: WorkPlanTool = {
+  type: 'work_plan_20250828',
+  name: 'work_plan',
+};
+
+/**
+ * Execute work plan command. This mutates server-side plan state for the session.
+ * Returns a short, user-readable summary used in the tool_result block.
+ */
+export async function executeWorkPlan(
+  sessionId: string,
+  input: WorkPlanCommand,
+): Promise<string> {
+  switch (input.command) {
+    case 'create': {
+      const items = (input.items || []).slice().sort((a, b) => a.order - b.order);
+      if (items.length === 0) {
+        return 'No work plan items provided';
+      }
+      await sessionStoreFs.recordWorkPlanCreate(sessionId, items);
+      // Notify: show the first current task
+      const snap = await sessionStoreFs.getSnapshot(sessionId);
+      const title = snap?.title || 'Agent';
+      const total = items.length;
+      const first = items[0]?.title || 'Step 1';
+      const deviceId = snap?.initiatorDeviceId || getInitiatorDeviceId(sessionId);
+      if (deviceId) {
+        await notificationsService.notifyAgentPlanProgress({
+          deviceId,
+          sessionId,
+          sessionTitle: title,
+          kind: 'created',
+          stepIndex: 1,
+          total,
+          taskTitle: first,
+        });
+      }
+      return `Work plan created with ${total} steps.`;
+    }
+
+    case 'complete': {
+      const res = await sessionStoreFs.recordWorkPlanComplete(sessionId, input.id);
+      if (!res) {
+        return `No matching step found for id ${input.id}`;
+      }
+      const snap = await sessionStoreFs.getSnapshot(sessionId);
+      const title = snap?.title || 'Agent';
+      const deviceId = snap?.initiatorDeviceId || getInitiatorDeviceId(sessionId);
+      if (deviceId) {
+        await notificationsService.notifyAgentPlanProgress({
+          deviceId,
+          sessionId,
+          sessionTitle: title,
+          kind: res.next ? 'next' : 'completed',
+          stepIndex: res.next ? res.completed + 1 : res.total,
+          total: res.total,
+          taskTitle: res.next?.title || 'All steps completed',
+        });
+      }
+      if (res.next) {
+        return `Completed step "${res.completedItem.title}". Next: (${res.completed + 1}/${res.total}) "${res.next.title}".`;
+      }
+      return `Completed step "${res.completedItem.title}". Plan finished (${res.total}/${res.total}).`;
+    }
+
+    case 'revise': {
+      const res = await sessionStoreFs.recordWorkPlanRevise(sessionId, input.items || []);
+      const count = res?.total ?? 0;
+      return `Revised work plan. Now ${count} steps.`;
+    }
+
+    default:
+      return `Unknown work_plan command`;
+  }
+}

src/agent/anthropic/types.ts

@@ -229,6 +229,43 @@ export interface TextEditorTool extends SpecialTool {
   name: 'str_replace_based_edit_tool';
 }
 
+// Work Plan Tool
+export interface WorkPlanTool extends SpecialTool {
+  type: 'work_plan_20250828';
+  name: 'work_plan';
+}
+
+export type WorkPlanCommand =
+  | WorkPlanCreateCommand
+  | WorkPlanCompleteCommand
+  | WorkPlanReviseCommand;
+
+export interface WorkPlanCreateCommand {
+  command: 'create';
+  items: Array<{
+    id: string;
+    title: string;
+    order: number;
+    estimated_seconds?: number;
+  }>;
+}
+
+export interface WorkPlanCompleteCommand {
+  command: 'complete';
+  id: string;
+}
+
+export interface WorkPlanReviseCommand {
+  command: 'revise';
+  items: Array<{
+    id: string;
+    title?: string;
+    order?: number;
+    estimated_seconds?: number;
+    remove?: boolean;
+  }>;
+}
+
 export type TextEditorCommand = 
   | ViewCommand
   | StrReplaceCommand
@@ -482,4 +519,4 @@ export interface ToolOutput {
   output: string;
   isError: boolean;
   input?: any;  // Optional, for context
-}
+}

src/agent/index.ts

@@ -5,7 +5,9 @@
 
 import { verifyAuthFromRequest } from '../auth/middleware';
 import type { Router } from '../server/router';
+import { wsManager } from '../server/websocket';
 import { handleAgentWebSocket, registerAgentRoutes } from './anthropic/index';
+import { setInitiatorDeviceId } from './session-initiators';
 import { sessionStoreFs } from './store/session-store-fs';
 
 /**
@@ -41,6 +43,18 @@ export async function handleAgentMessage(
 ): Promise<void> {
   // Route based on message type prefix
   if (message.type?.startsWith('agent:')) {
+    // Capture initiator device for this session (for targeted pushes)
+    try {
+      if (message.type === 'agent:message' && typeof message.sessionId === 'string') {
+        const client = wsManager.getClient(clientId);
+        const deviceId = (client?.metadata as any)?.deviceId as string | undefined;
+        if (deviceId) {
+          setInitiatorDeviceId(message.sessionId, deviceId);
+          // Persist if snapshot already exists
+          void sessionStoreFs.setInitiator(message.sessionId, deviceId);
+        }
+      }
+    } catch {}
     // Default to Anthropic for now
     await handleAgentWebSocket(ws, clientId, message);
   }
@@ -59,4 +73,4 @@ export type {
   ServerMessage,
   ToolOutput, 
   ToolRequest
-} from './anthropic/types';
+} from './anthropic/types';

src/agent/session-initiators.ts

@@ -0,0 +1,19 @@
+/**
+ * Simple in-memory mapping of agent session -> initiating deviceId.
+ * This complements the persisted snapshot's initiatorDeviceId, providing
+ * an early mapping before the snapshot is created.
+ */
+
+const initiators = new Map<string, string>();
+
+export function setInitiatorDeviceId(sessionId: string, deviceId: string): void {
+  if (!sessionId || !deviceId) return;
+  if (!initiators.has(sessionId)) {
+    initiators.set(sessionId, deviceId);
+  }
+}
+
+export function getInitiatorDeviceId(sessionId: string): string | undefined {
+  return initiators.get(sessionId);
+}
+