@stigmer/runner 3.0.1

package/src/activities/execute-deep-agent/inline-publisher.ts

@@ -0,0 +1,134 @@
+/**
+ * Inline artifact publisher for streaming execution.
+ *
+ * Publishes artifacts as they are written during the LangGraph event stream,
+ * so the UI can display them in real time without waiting for the post-stream
+ * safety net.
+ *
+ * Designed as a fire-and-forget callback: exceptions are logged and
+ * swallowed so the streaming loop is never interrupted.
+ *
+ * DD-7: No skill-aware directory publishing. Individual files only.
+ */
+
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+import { create } from "@bufbuild/protobuf";
+import { ExecutionArtifactSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import {
+  ExecutionArtifactKind,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ArtifactStorage } from "../../shared/artifact-storage.js";
+import type { WorkspaceBackend } from "../../shared/workspace/types.js";
+import type { ExecutionStatusWriter } from "./execution-status-writer.js";
+import { utcTimestamp } from "../../shared/status.js";
+
+export class InlinePublisher {
+  private readonly workspaceBackend: WorkspaceBackend;
+  private readonly artifactStorage: ArtifactStorage;
+  private readonly statusWriter: ExecutionStatusWriter;
+  private readonly executionId: string;
+
+  /** Tracks (sandboxPath -> contentHash) for deduplication. */
+  private readonly published = new Map<string, string>();
+
+  constructor(opts: {
+    workspaceBackend: WorkspaceBackend;
+    artifactStorage: ArtifactStorage;
+    statusWriter: ExecutionStatusWriter;
+    executionId: string;
+  }) {
+    this.workspaceBackend = opts.workspaceBackend;
+    this.artifactStorage = opts.artifactStorage;
+    this.statusWriter = opts.statusWriter;
+    this.executionId = opts.executionId;
+  }
+
+  /** Set of sandbox paths that have been published (for auto-publish dedup). */
+  get publishedPaths(): ReadonlySet<string> {
+    return new Set(this.published.keys());
+  }
+
+  /**
+   * Upload the file at `path` to artifact storage and register it on the
+   * status builder. Fire-and-forget: errors are logged and swallowed.
+   */
+  async publish(path: string): Promise<void> {
+    try {
+      const sandboxPath = normalizePath(path);
+
+      const content = await this.workspaceBackend.readFile(sandboxPath);
+      const contentBuffer = Buffer.from(content, "utf-8");
+      const contentHash = sha256(contentBuffer);
+
+      if (this.published.get(sandboxPath) === contentHash) {
+        return;
+      }
+
+      const fileName = basename(sandboxPath);
+      const storageKey = `artifacts/${this.executionId}/${fileName}`;
+
+      await this.artifactStorage.upload(storageKey, contentBuffer, guessContentType(fileName));
+      const downloadUrl = await this.artifactStorage.getDownloadUrl(storageKey);
+
+      const artifact = create(ExecutionArtifactSchema, {
+        name: fileName,
+        sandboxPath,
+        kind: ExecutionArtifactKind.FILE,
+        sizeBytes: BigInt(contentBuffer.length),
+        storageKey,
+        downloadUrl,
+        createdAt: utcTimestamp(),
+        contentHash,
+      });
+
+      this.statusWriter.addArtifact(artifact);
+      this.published.set(sandboxPath, contentHash);
+
+      console.log(
+        `[InlinePublisher] execution=${this.executionId} — published '${sandboxPath}' ` +
+        `(${contentBuffer.length} bytes, hash=${contentHash.slice(0, 12)})`,
+      );
+    } catch (err) {
+      console.warn(
+        `[InlinePublisher] execution=${this.executionId} — ` +
+        `failed to publish '${path}' (non-fatal): ${err}`,
+      );
+    }
+  }
+}
+
+function normalizePath(path: string): string {
+  return path.replace(/^\/+/, "");
+}
+
+function sha256(content: Buffer): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+const CONTENT_TYPE_MAP: Record<string, string> = {
+  ".txt": "text/plain",
+  ".md": "text/markdown",
+  ".json": "application/json",
+  ".js": "application/javascript",
+  ".ts": "application/typescript",
+  ".py": "text/x-python",
+  ".html": "text/html",
+  ".css": "text/css",
+  ".xml": "text/xml",
+  ".yaml": "text/yaml",
+  ".yml": "text/yaml",
+  ".csv": "text/csv",
+  ".pdf": "application/pdf",
+  ".zip": "application/zip",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+};
+
+function guessContentType(filename: string): string {
+  const ext = filename.slice(filename.lastIndexOf(".")).toLowerCase();
+  return CONTENT_TYPE_MAP[ext] ?? "application/octet-stream";
+}

package/src/activities/execute-deep-agent/post-stream.ts

@@ -0,0 +1,109 @@
+/**
+ * Post-stream processing for deep agent execution.
+ *
+ * Orchestrates cleanup tasks after the LangGraph stream completes:
+ *  1. Drain pending inline publish promises (fire-and-forget completions).
+ *  2. Auto-publish safety net (scan tool calls for missed files).
+ *  3. Writeback finalize (commit remaining uncommitted changes).
+ *
+ * Each step is independently try/caught. A failure in one step does not
+ * block subsequent steps — the execution still completes.
+ */
+
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { InlinePublisher } from "./inline-publisher.js";
+import type { WriteBackCoordinator } from "./writeback-coordinator.js";
+import { autoPublishWrittenFiles } from "./auto-publish.js";
+
+export interface PostStreamOptions {
+  readonly status: AgentExecutionStatus;
+  readonly inlinePublisher: InlinePublisher;
+  readonly writebackCoordinator: WriteBackCoordinator | null;
+  readonly pendingPublishPromises: readonly Promise<void>[];
+  readonly pendingWritebackPromises: readonly Promise<void>[];
+  readonly executionId: string;
+}
+
+export async function processPostStream(opts: PostStreamOptions): Promise<void> {
+  const {
+    status,
+    inlinePublisher,
+    writebackCoordinator,
+    pendingPublishPromises,
+    pendingWritebackPromises,
+    executionId,
+  } = opts;
+
+  if (status.phase === ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL ||
+      status.phase === ExecutionPhase.EXECUTION_PAUSED) {
+    const phaseName = status.phase === ExecutionPhase.EXECUTION_PAUSED
+      ? "PAUSED" : "WAITING_FOR_APPROVAL";
+
+    if (pendingPublishPromises.length > 0 || pendingWritebackPromises.length > 0) {
+      await Promise.allSettled([...pendingPublishPromises, ...pendingWritebackPromises]);
+      console.log(
+        `[postStream] execution=${executionId} — drained pending promises ` +
+        `(phase is ${phaseName})`,
+      );
+    }
+    return;
+  }
+
+  // Step 1: Drain pending inline publish promises
+  if (pendingPublishPromises.length > 0) {
+    try {
+      await Promise.allSettled(pendingPublishPromises);
+      console.log(
+        `[postStream] execution=${executionId} — ` +
+        `drained ${pendingPublishPromises.length} pending publish task(s)`,
+      );
+    } catch (err) {
+      console.warn(
+        `[postStream] execution=${executionId} — ` +
+        `error draining publish tasks: ${err}`,
+      );
+    }
+  }
+
+  // Step 2: Drain pending writeback promises
+  if (pendingWritebackPromises.length > 0) {
+    try {
+      await Promise.allSettled(pendingWritebackPromises);
+      console.log(
+        `[postStream] execution=${executionId} — ` +
+        `drained ${pendingWritebackPromises.length} pending writeback task(s)`,
+      );
+    } catch (err) {
+      console.warn(
+        `[postStream] execution=${executionId} — ` +
+        `error draining writeback tasks: ${err}`,
+      );
+    }
+  }
+
+  // Step 3: Auto-publish safety net
+  try {
+    await autoPublishWrittenFiles(status, inlinePublisher);
+  } catch (err) {
+    console.warn(
+      `[postStream] execution=${executionId} — ` +
+      `auto-publish safety net error: ${err}`,
+    );
+  }
+
+  // Step 4: Writeback finalize
+  if (writebackCoordinator) {
+    try {
+      await writebackCoordinator.finalize();
+      console.log(
+        `[postStream] execution=${executionId} — writeback finalize complete`,
+      );
+    } catch (err) {
+      console.warn(
+        `[postStream] execution=${executionId} — ` +
+        `writeback finalize error: ${err}`,
+      );
+    }
+  }
+}

package/src/activities/execute-deep-agent/prompt-builder.ts

@@ -0,0 +1,264 @@
+/**
+ * System prompt construction for deep agent execution.
+ *
+ * Pure functions: no side effects, no I/O. Accepts pre-computed data
+ * (provision results, skill sections, file refs) and returns the
+ * assembled system prompt string.
+ */
+
+import { relative } from "node:path";
+import type { ProvisionResult, GitMetadata } from "../../shared/workspace/types.js";
+import { SourceType } from "../../shared/workspace/types.js";
+
+const RESPONSE_RULES = `
+
+## Response rules
+
+- After using the read tool, NEVER reprint, echo, list, or summarize \
+file contents in your response. Tool results are already in your \
+context. Proceed directly to analysis or the task.
+- Do not begin responses with phrases like \
+"Below is the complete content", \
+"Here are the contents of the files", or similar. \
+The user did not ask you to display file contents.
+- Use backticks for file paths, function names, variable names, \
+and shell commands (e.g., \`src/main.py\`, \`handleRequest()\`, \
+\`npm install\`).
+- When referencing code, cite the file path — do not re-print \
+code blocks that the user can see in tool results.
+- Structure complex answers with headings and bullet points.
+- If you encounter something unexpected that changes the scope, \
+explain the issue and propose options before proceeding.
+`;
+
+const SUB_AGENT_RULES = `
+
+## Sub-agent delegation rules
+
+### Concurrency limit
+
+Do NOT spawn more than 3 sub-agents concurrently. If you need to \
+explore more than 3 areas, batch them: launch the first 3, wait for \
+results, then launch more if needed. The runtime enforces this limit — \
+excess sub-agents will be rejected.
+
+### When NOT to delegate
+
+- **Reading files.** Use the \`read\` tool yourself. You need raw file \
+contents in your own context to reason about them accurately.
+- **Single-step lookups.** Use \`grep\`, \`glob\`, \`search\`, or \`read\` \
+directly for simple searches across 1-2 files. Only delegate when \
+the task requires multi-step exploration.
+- **Data you will process yourself.** If you need the output in your \
+own context (e.g., to answer a question, write code, compare files), \
+do the work directly — do not delegate it.
+- **Small tasks (fewer than 3 steps).** The overhead of spawning a \
+sub-agent outweighs the benefit for trivial operations.
+
+### When TO delegate
+
+- Multi-step, independent tasks that produce a deliverable (analysis, \
+synthesis, generated content) you will incorporate into your response.
+- Parallel exploration of genuinely different areas of a codebase or \
+knowledge base when context isolation helps.
+- Tasks that benefit from a separate context window (e.g., long \
+document summarization that would crowd your own context).
+
+### Delegation best practices
+
+- When delegating, specify the **deliverable** you need — not \
+"read these files and give me the contents."
+- You MUST reference and synthesize sub-agent results in your \
+response. If you spawn a sub-agent, its output must visibly \
+influence your answer.
+- Each sub-agent consumes tokens and time. Prefer doing work \
+directly over delegating. Only delegate when context isolation \
+or parallelism genuinely helps the user.
+`;
+
+export interface PromptBuilderInput {
+  instructions: string;
+  provisionResults: ProvisionResult[];
+  containerRoot: string;
+  skillsPromptSection: string;
+  workspaceFileRefs: string[];
+  workspaceRoot: string;
+  injectedFiles: InjectedFile[];
+}
+
+export interface InjectedFile {
+  filename: string;
+  path: string;
+  size?: number | null;
+}
+
+/**
+ * Assemble the full system prompt from base instructions and contextual
+ * sections. Pure function with no I/O.
+ */
+export function buildEnhancedSystemPrompt(input: PromptBuilderInput): string {
+  let prompt = input.instructions;
+
+  const workspaceSection = buildWorkspacePromptSection(
+    input.provisionResults,
+    input.containerRoot,
+  );
+  if (workspaceSection) {
+    prompt += workspaceSection;
+  }
+
+  if (input.skillsPromptSection) {
+    prompt += input.skillsPromptSection;
+  }
+
+  if (input.workspaceFileRefs.length > 0) {
+    const refSection = buildReferencedFilesSection(
+      input.workspaceFileRefs,
+      input.workspaceRoot,
+    );
+    if (refSection) {
+      prompt += refSection;
+    }
+  }
+
+  if (input.injectedFiles.length > 0) {
+    prompt += buildInjectedFilesSection(input.injectedFiles);
+  }
+
+  prompt += RESPONSE_RULES;
+  prompt += SUB_AGENT_RULES;
+
+  return prompt;
+}
+
+function buildWorkspacePromptSection(
+  provisionResults: ProvisionResult[],
+  containerRoot: string,
+): string {
+  if (provisionResults.length === 0) return "";
+
+  if (provisionResults.length === 1) {
+    return buildSingleWorkspaceSection(provisionResults[0]);
+  }
+  return buildMultiWorkspaceSection(provisionResults, containerRoot);
+}
+
+function buildSingleWorkspaceSection(result: ProvisionResult): string {
+  if (!result.workspaceDescription) return "";
+
+  let section = "\n\n## Workspace\n\n" + result.workspaceDescription;
+  if (result.fileTree) {
+    section += "\n\n" + result.fileTree;
+  }
+  return section;
+}
+
+function buildMultiWorkspaceSection(
+  results: ProvisionResult[],
+  containerRoot: string,
+): string {
+  const firstLabel = results[0].entryName || "entry-1";
+
+  let section =
+    `\n\n## Workspace\n\n` +
+    `This session has ${results.length} workspace entries.\n\n` +
+    `**Path resolution**: All tools resolve paths relative to the ` +
+    `workspace root. Use entry-relative paths ` +
+    `(e.g., \`${firstLabel}/src/main.py\`). ` +
+    `Do not use absolute filesystem paths.\n`;
+
+  for (let idx = 0; idx < results.length; idx++) {
+    const result = results[idx];
+    const label = result.entryName || `entry-${idx + 1}`;
+    const relPath = workspaceRelativePath(result.rootDir, containerRoot);
+    section += `\n### ${label} (\`${relPath}\`)\n\n`;
+    section += formatEntryDescription(result);
+    if (result.fileTree) {
+      section += "\n\n" + result.fileTree;
+    }
+  }
+
+  return section;
+}
+
+function workspaceRelativePath(rootDir: string, containerRoot: string): string {
+  if (!containerRoot) return rootDir;
+  try {
+    const rel = relative(containerRoot, rootDir);
+    if (rel.startsWith("..")) return rootDir;
+    return rel;
+  } catch {
+    return rootDir;
+  }
+}
+
+function formatEntryDescription(result: ProvisionResult): string {
+  const name = result.entryName || "this entry";
+
+  if (result.sourceType === SourceType.LOCAL_PATH) {
+    return (
+      `Workspace entry **${name}** is the user's project directory ` +
+      `at \`${result.rootDir}\`.\n` +
+      "You are operating directly on the user's files — changes are " +
+      "immediate and persistent. Use git to track and verify your changes."
+    );
+  }
+
+  if (result.sourceType === SourceType.GIT_REPO && result.gitMetadata) {
+    const meta: GitMetadata = result.gitMetadata;
+    const shortSha = meta.baseCommit.length >= 7
+      ? meta.baseCommit.slice(0, 7)
+      : meta.baseCommit;
+    return (
+      `Workspace entry **${name}** was initialized from ` +
+      `${meta.repoUrl} (branch: ${meta.branch}, commit: ${shortSha}).\n` +
+      "Changes you make will be captured as artifacts when execution completes."
+    );
+  }
+
+  if (result.sourceType === SourceType.EMPTY) {
+    return (
+      `Workspace entry **${name}** is an empty workspace.\n` +
+      "Create files and directories as needed for your task."
+    );
+  }
+
+  return result.workspaceDescription;
+}
+
+function buildReferencedFilesSection(
+  workspaceFileRefs: string[],
+  _workspaceRoot: string,
+): string {
+  if (workspaceFileRefs.length === 0) return "";
+
+  let section =
+    "\n\n## Referenced Files\n\n" +
+    "The user has highlighted the following workspace paths for your " +
+    "attention. Use `read` to access file contents.\n\n";
+
+  for (const refPath of workspaceFileRefs) {
+    section += `- \`${refPath}\`\n`;
+  }
+
+  return section;
+}
+
+function buildInjectedFilesSection(files: InjectedFile[]): string {
+  let section = "\n\n## Input Files\n\n";
+  section +=
+    "The following files have been provided as read-only reference " +
+    "material for your task. They live under `.stigmer/inputs/` and " +
+    "are NOT part of the project source tree.\n\n" +
+    "Read them using the `read` tool when you need their contents. " +
+    "Do NOT echo, reprint, or summarize file contents in your response " +
+    "-- they are reference material, not output. " +
+    "Do NOT modify or delete these files.\n\n";
+
+  for (const f of files) {
+    const sizeInfo = f.size != null ? ` (${f.size} bytes)` : "";
+    section += `- \`${f.path}\`${sizeInfo}\n`;
+  }
+
+  return section;
+}