feat: add walkthrough as subagent

Author: leslieo2

.pochi/agents/walkthroughs.md

@@ -0,0 +1,24 @@
+---
+name: walkthroughs
+description: Create or update walkthrough summaries for a task when the user requests a walkthrough or project recap.
+tools: readFile, writeToFile, listFiles
+---
+
+You are a walkthrough authoring agent. Your job is to produce a concise Markdown walkthrough that helps a new reader get up to speed with the work completed in a task.
+
+When invoked:
+1. Identify the task id and target path. If the prompt provides an absolute path, use it; otherwise use `pochi/walkthroughs/$taskId.md`.
+2. Review the conversation and tool outputs for requirements and actual changes.
+3. Summarize key work items, notable file changes, and any commands run.
+4. Include outcomes and any remaining follow-ups or known gaps.
+5. If references to screenshots or recordings are available, include them as links or notes.
+6. Write the walkthrough to the target path using `writeToFile`.
+
+Output rules:
+- Write Markdown to the target file only (use `writeToFile`).
+- After finishing, call `attemptCompletion` with: "Walkthrough created at <path>".
+- Do not include any other response text outside the tool call.
+- If you need to check whether the walkthrough file exists, try `readFile` on the target path; if it fails, proceed as a new file.
+- Prefer short sections with bullets over long paragraphs.
+- Keep it concise and actionable.
+- If an existing walkthrough file is present, append an "Update" section rather than overwriting.

packages/common/src/base/constants.ts

@@ -7,6 +7,11 @@ export const KnownTags = [
 ] as const;
 export const CompactTaskMinTokens = 50_000;
 
+// Built-in agent names
+export const WALKTHROUGH_AGENT_NAME = "walkthroughs";
+export const EXPLORE_AGENT_NAME = "explore";
+export const DEBUGGER_AGENT_NAME = "debugger";
+
 export const WorkspaceWorkflowPathSegments = [".pochi", "workflows"];
 
 export const DefaultContextWindow = 100_000;

packages/common/src/base/index.ts

@@ -7,6 +7,11 @@ export { prompts } from "./prompts";
 
 export { SocialLinks } from "./social";
 export * as constants from "./constants";
+export {
+  WALKTHROUGH_AGENT_NAME,
+  EXPLORE_AGENT_NAME,
+  DEBUGGER_AGENT_NAME,
+} from "./constants";
 
 export {
   Environment,

packages/common/src/vscode-webui-bridge/webview-stub.ts

@@ -173,6 +173,9 @@ const VSCodeHostStub = {
   openExternal: (_uri: string): Promise<void> => {
     return Promise.resolve();
   },
+  checkFileExists: async (_path: string): Promise<boolean> => {
+    return Promise.resolve(false);
+  },
   readMinionId: async () => {
     return Promise.resolve(null);
   },

packages/common/src/vscode-webui-bridge/webview.ts

@@ -223,6 +223,13 @@ export interface VSCodeHostApi {
    */
   openExternal(uri: string): Promise<void>;
 
+  /**
+   * Checks if a file exists at the given path.
+   * @param path - The file path to check.
+   * @returns A promise that resolves to true if the file exists, false otherwise.
+   */
+  checkFileExists(path: string): Promise<boolean>;
+
   /**
    * Saves a checkpoint with the given message.
    * @param message - The message to save as a checkpoint.

packages/livekit/src/chat/middlewares/new-task-middleware.ts

@@ -3,9 +3,11 @@ import type {
   LanguageModelV2StreamPart,
 } from "@ai-sdk/provider";
 import { safeParseJSON } from "@ai-sdk/provider-utils";
+import { WALKTHROUGH_AGENT_NAME } from "@getpochi/common";
 import { type CustomAgent, newTaskInputSchema } from "@getpochi/tools";
 import type { Store } from "@livestore/livestore";
 import { InvalidToolInputError } from "ai";
+import { makeMessagesQuery } from "../../livestore/default-queries";
 import { events } from "../../livestore/default-schema";
 
 export function createNewTaskMiddleware(
@@ -14,6 +16,17 @@ export function createNewTaskMiddleware(
   parentTaskId: string,
   customAgents?: CustomAgent[],
 ): LanguageModelV2Middleware {
+  const builtinAgentDefaults: Record<
+    string,
+    {
+      inheritParentMessages?: boolean;
+    }
+  > = {
+    [WALKTHROUGH_AGENT_NAME]: {
+      inheritParentMessages: true,
+    },
+  };
+
   return {
     middlewareVersion: "v2",
     transformParams: async ({ params }) => {
@@ -95,13 +108,25 @@ export function createNewTaskMiddleware(
               args._meta = {
                 uid,
               };
+              const agentType = args.agentType ?? "";
+              const shouldInheritParentMessages =
+                args.inheritParentMessages ??
+                builtinAgentDefaults[agentType]?.inheritParentMessages ??
+                false;
+              const parentMessages = shouldInheritParentMessages
+                ? store.query(makeMessagesQuery(parentTaskId)).map((x) => ({
+                    ...x.data,
+                    id: crypto.randomUUID(),
+                  }))
+                : [];
               store.commit(
                 events.taskInited({
                   id: uid,
                   cwd,
                   parentId: parentTaskId,
                   createdAt: new Date(),
                   initMessages: [
+                    ...parentMessages,
                     {
                       id: crypto.randomUUID(),
                       role: "user",

packages/livekit/src/chat/walkthrough.ts

@@ -0,0 +1,3 @@
+export function getWalkthroughPath(taskId: string): string {
+  return `pochi/walkthroughs/${taskId}.md`;
+}

packages/livekit/src/index.ts

@@ -11,3 +11,4 @@ export type {
 
 export const StoreBlobProtocol = "store-blob:";
 export { processContentOutput, fileToUri } from "./store-blob";
+export { getWalkthroughPath } from "./chat/walkthrough";

packages/tools/src/new-task.ts

@@ -64,6 +64,10 @@ export const inputSchema = z.object({
     .string()
     .optional()
     .describe("The type of the specialized agent to use for the task."),
+  inheritParentMessages: z
+    .boolean()
+    .optional()
+    .describe("Whether to inherit the parent task's messages."),
   _meta: z
     .object({
       uid: z.string().describe("A unique identifier for the task."),

packages/vscode-webui/src/components/message/message-list.tsx

@@ -47,6 +47,7 @@ export const MessageList: React.FC<{
   showLoader?: boolean;
   forkTask?: (commitId: string, messageId?: string) => Promise<void>;
   hideCheckPoint?: boolean;
+  taskId?: string;
 }> = ({
   messages: renderMessages,
   isLoading,
@@ -58,6 +59,7 @@ export const MessageList: React.FC<{
   showLoader = true,
   forkTask,
   hideCheckPoint,
+  taskId,
 }) => {
   const [debouncedIsLoading, setDebouncedIsLoading] = useDebounceState(
     isLoading,
@@ -139,6 +141,7 @@ export const MessageList: React.FC<{
                     hideCheckPoint={hideCheckPoint}
                     latestCheckpoint={latestCheckpoint}
                     lastCheckpointInMessage={lastCheckpointInMessage}
+                    taskId={taskId}
                   />
                 ))}
               </div>
@@ -200,6 +203,7 @@ function Part({
   hideCheckPoint,
   latestCheckpoint,
   lastCheckpointInMessage,
+  taskId,
 }: {
   role: Message["role"];
   partIndex: number;
@@ -212,6 +216,7 @@ function Part({
   hideCheckPoint?: boolean;
   latestCheckpoint: string | null;
   lastCheckpointInMessage: string | undefined;
+  taskId?: string;
 }) {
   const paddingClass = partIndex === 0 ? "" : "mt-2";
   if (part.type === "text") {
@@ -261,6 +266,7 @@ function Part({
         isLoading={isLoading}
         changes={getToolCallCheckpoint(part, messages)}
         messages={messages}
+        taskId={taskId}
       />
     );
   }