stagent 0.6.2 → 0.6.3

package/src/lib/chat/tools/settings-tools.ts

@@ -2,6 +2,76 @@ import { defineTool } from "../tool-registry";
 import { z } from "zod";
 import { ok, err, type ToolContext } from "./helpers";
 
+/* ── Writable settings allowlist ─────────────────────────────────── */
+
+interface WritableSetting {
+  validate: (value: string) => string | null; // error message or null
+  description: string;
+}
+
+const WRITABLE_SETTINGS: Record<string, WritableSetting> = {
+  "runtime.sdkTimeoutSeconds": {
+    description: "SDK timeout in seconds (10–300)",
+    validate: (v) => {
+      const n = parseInt(v, 10);
+      return isNaN(n) || n < 10 || n > 300 ? "Must be integer 10–300" : null;
+    },
+  },
+  "runtime.maxTurns": {
+    description: "Max agent turns per task (1–50)",
+    validate: (v) => {
+      const n = parseInt(v, 10);
+      return isNaN(n) || n < 1 || n > 50 ? "Must be integer 1–50" : null;
+    },
+  },
+  "routing.preference": {
+    description: "Routing preference: cost | latency | quality | manual",
+    validate: (v) =>
+      ["cost", "latency", "quality", "manual"].includes(v)
+        ? null
+        : "Must be one of: cost, latency, quality, manual",
+  },
+  "browser.chromeDevtoolsEnabled": {
+    description: "Enable Chrome DevTools MCP: true | false",
+    validate: (v) =>
+      ["true", "false"].includes(v) ? null : "Must be 'true' or 'false'",
+  },
+  "browser.playwrightEnabled": {
+    description: "Enable Playwright MCP: true | false",
+    validate: (v) =>
+      ["true", "false"].includes(v) ? null : "Must be 'true' or 'false'",
+  },
+  "web.exaSearchEnabled": {
+    description: "Enable Exa web search: true | false",
+    validate: (v) =>
+      ["true", "false"].includes(v) ? null : "Must be 'true' or 'false'",
+  },
+  "learning.contextCharLimit": {
+    description: "Learning context char limit (2000–32000, step 1000)",
+    validate: (v) => {
+      const n = parseInt(v, 10);
+      return isNaN(n) || n < 2000 || n > 32000 || n % 1000 !== 0
+        ? "Must be integer 2000–32000, step 1000"
+        : null;
+    },
+  },
+  "ollama.baseUrl": {
+    description: "Ollama server base URL",
+    validate: (v) => (v.trim().length === 0 ? "Must be non-empty URL" : null),
+  },
+  "ollama.defaultModel": {
+    description: "Default Ollama model name",
+    validate: (v) =>
+      v.trim().length === 0 ? "Must be non-empty string" : null,
+  },
+};
+
+const WRITABLE_KEYS_DOC = Object.entries(WRITABLE_SETTINGS)
+  .map(([k, v]) => `- "${k}": ${v.description}`)
+  .join("\n");
+
+/* ── Tool definitions ────────────────────────────────────────────── */
+
 export function settingsTools(_ctx: ToolContext) {
   return [
     defineTool(
@@ -69,5 +139,44 @@ export function settingsTools(_ctx: ToolContext) {
         }
       }
     ),
+
+    defineTool(
+      "set_settings",
+      `Update a Stagent setting. Requires user approval.\n\nWritable keys:\n${WRITABLE_KEYS_DOC}`,
+      {
+        key: z.string().describe("Setting key to update"),
+        value: z.string().describe("New value (always a string)"),
+      },
+      async (args) => {
+        const spec = WRITABLE_SETTINGS[args.key];
+        if (!spec) {
+          return err(
+            `Key "${args.key}" is not writable. Valid keys: ${Object.keys(WRITABLE_SETTINGS).join(", ")}`
+          );
+        }
+        const validationError = spec.validate(args.value);
+        if (validationError) {
+          return err(
+            `Invalid value for "${args.key}": ${validationError}`
+          );
+        }
+        try {
+          const { getSetting, setSetting } = await import(
+            "@/lib/settings/helpers"
+          );
+          const oldValue = await getSetting(args.key);
+          await setSetting(args.key, args.value);
+          return ok({
+            key: args.key,
+            oldValue: oldValue ?? "(unset)",
+            newValue: args.value,
+          });
+        } catch (e) {
+          return err(
+            e instanceof Error ? e.message : "Failed to update setting"
+          );
+        }
+      }
+    ),
   ];
 }

package/src/lib/chat/tools/workflow-tools.ts

@@ -1,8 +1,15 @@
 import { defineTool } from "../tool-registry";
 import { z } from "zod";
 import { db } from "@/lib/db";
-import { workflows, tasks, agentLogs, notifications, documents } from "@/lib/db/schema";
-import { eq, and, desc } from "drizzle-orm";
+import {
+  workflows,
+  tasks,
+  agentLogs,
+  notifications,
+  documents,
+  workflowDocumentInputs,
+} from "@/lib/db/schema";
+import { eq, and, desc, inArray, like } from "drizzle-orm";
 import { ok, err, type ToolContext } from "./helpers";
 
 const VALID_WORKFLOW_STATUSES = [
@@ -74,6 +81,12 @@ export function workflowTools(ctx: ToolContext) {
           .describe(
             'Workflow definition as JSON string. Must include "pattern" and "steps" array. Example: {"pattern":"sequence","steps":[{"name":"step1","prompt":"Do X","assignedAgent":"claude"}]}'
           ),
+        documentIds: z
+          .array(z.string())
+          .optional()
+          .describe(
+            "Optional array of document IDs from the project pool to attach as input context. These documents will be injected into all workflow steps at execution time."
+          ),
       },
       async (args) => {
         try {
@@ -103,6 +116,25 @@ export function workflowTools(ctx: ToolContext) {
             updatedAt: now,
           });
 
+          // Attach pool documents if provided
+          const attachedDocs: string[] = [];
+          if (args.documentIds && args.documentIds.length > 0) {
+            for (const docId of args.documentIds) {
+              try {
+                await db.insert(workflowDocumentInputs).values({
+                  id: crypto.randomUUID(),
+                  workflowId: id,
+                  documentId: docId,
+                  stepId: null,
+                  createdAt: now,
+                });
+                attachedDocs.push(docId);
+              } catch {
+                // Skip duplicates or invalid doc IDs
+              }
+            }
+          }
+
           const [workflow] = await db
             .select()
             .from(workflows)
@@ -115,6 +147,7 @@ export function workflowTools(ctx: ToolContext) {
             projectId: workflow.projectId,
             status: workflow.status,
             createdAt: workflow.createdAt,
+            attachedDocuments: attachedDocs.length,
           });
         } catch (e) {
           return err(e instanceof Error ? e.message : "Failed to create workflow");
@@ -354,5 +387,115 @@ export function workflowTools(ctx: ToolContext) {
         }
       }
     ),
+
+    defineTool(
+      "find_related_documents",
+      "Search for documents in the project pool that could be used as context for a workflow. Returns output documents from completed workflows and uploaded documents. Use this proactively when creating follow-up workflows to discover relevant context.",
+      {
+        projectId: z
+          .string()
+          .optional()
+          .describe("Project ID to search in. Omit to use the active project."),
+        query: z
+          .string()
+          .optional()
+          .describe("Search query to match against document names"),
+        direction: z
+          .enum(["input", "output"])
+          .optional()
+          .describe('Filter by direction. Use "output" to find documents produced by other workflows.'),
+        sourceWorkflowId: z
+          .string()
+          .optional()
+          .describe("Filter to documents produced by a specific workflow"),
+        limit: z
+          .number()
+          .optional()
+          .describe("Maximum number of documents to return (default: 20)"),
+      },
+      async (args) => {
+        try {
+          const effectiveProjectId = args.projectId ?? ctx.projectId ?? undefined;
+          if (!effectiveProjectId) {
+            return err("No project context — specify a projectId or set an active project");
+          }
+
+          const conditions = [
+            eq(documents.projectId, effectiveProjectId),
+            eq(documents.status, "ready"),
+          ];
+
+          if (args.direction) {
+            conditions.push(eq(documents.direction, args.direction));
+          }
+
+          if (args.query) {
+            conditions.push(like(documents.originalName, `%${args.query}%`));
+          }
+
+          if (args.sourceWorkflowId) {
+            // Find task IDs belonging to the source workflow
+            const workflowTasks = await db
+              .select({ id: tasks.id })
+              .from(tasks)
+              .where(eq(tasks.workflowId, args.sourceWorkflowId));
+
+            const taskIds = workflowTasks.map((t) => t.id);
+            if (taskIds.length > 0) {
+              conditions.push(inArray(documents.taskId, taskIds));
+            } else {
+              return ok([]); // No tasks for this workflow
+            }
+          }
+
+          const result = await db
+            .select({
+              id: documents.id,
+              originalName: documents.originalName,
+              mimeType: documents.mimeType,
+              size: documents.size,
+              direction: documents.direction,
+              category: documents.category,
+              status: documents.status,
+              taskId: documents.taskId,
+              createdAt: documents.createdAt,
+            })
+            .from(documents)
+            .where(and(...conditions))
+            .orderBy(desc(documents.createdAt))
+            .limit(args.limit ?? 20);
+
+          // Enrich with source workflow name
+          const enriched = await Promise.all(
+            result.map(async (doc) => {
+              let sourceWorkflowName: string | null = null;
+              if (doc.taskId) {
+                const [task] = await db
+                  .select({ workflowId: tasks.workflowId })
+                  .from(tasks)
+                  .where(eq(tasks.id, doc.taskId));
+                if (task?.workflowId) {
+                  const [wf] = await db
+                    .select({ name: workflows.name })
+                    .from(workflows)
+                    .where(eq(workflows.id, task.workflowId));
+                  sourceWorkflowName = wf?.name ?? null;
+                }
+              }
+              return {
+                ...doc,
+                sourceWorkflow: sourceWorkflowName,
+              };
+            })
+          );
+
+          return ok(enriched);
+        } catch (e) {
+          return err(
+            e instanceof Error ? e.message : "Failed to find documents"
+          );
+        }
+      }
+    ),
   ];
 }

package/src/lib/data/clear.ts

@@ -25,6 +25,9 @@ import {
   channelBindings,
   channelConfigs,
   agentMessages,
+  workflowDocumentInputs,
+  scheduleDocumentInputs,
+  projectDocumentDefaults,
 } from "@/lib/db/schema";
 import { readdirSync, unlinkSync, mkdirSync } from "fs";
 import { join } from "path";
@@ -71,6 +74,12 @@ export function clearAllData() {
   const usageLedgerDeleted = db.delete(usageLedger).run().changes;
   const logsDeleted = db.delete(agentLogs).run().changes;
   const notificationsDeleted = db.delete(notifications).run().changes;
+
+  // Document junction tables — delete before documents, workflows, schedules, projects
+  const workflowDocInputsDeleted = db.delete(workflowDocumentInputs).run().changes;
+  const scheduleDocInputsDeleted = db.delete(scheduleDocumentInputs).run().changes;
+  const projectDocDefaultsDeleted = db.delete(projectDocumentDefaults).run().changes;
+
   const documentsDeleted = db.delete(documents).run().changes;
   const agentMemoryDeleted = db.delete(agentMemory).run().changes;
   const learnedContextDeleted = db.delete(learnedContext).run().changes;
@@ -130,6 +139,9 @@ export function clearAllData() {
     agentMessages: agentMessagesDeleted,
     channelBindings: channelBindingsDeleted,
     channelConfigs: channelConfigsDeleted,
+    workflowDocumentInputs: workflowDocInputsDeleted,
+    scheduleDocumentInputs: scheduleDocInputsDeleted,
+    projectDocumentDefaults: projectDocDefaultsDeleted,
     files: filesDeleted,
     screenshots: screenshotsDeleted,
   };

package/src/lib/db/bootstrap.ts

@@ -28,6 +28,9 @@ const STAGENT_TABLES = [
   "channel_configs",
   "channel_bindings",
   "agent_messages",
+  "workflow_document_inputs",
+  "schedule_document_inputs",
+  "project_document_defaults",
 ] as const;
 
 export function bootstrapStagentDatabase(sqlite: Database.Database): void {
@@ -55,6 +58,7 @@ export function bootstrapStagentDatabase(sqlite: Database.Database): void {
       result TEXT,
       session_id TEXT,
       resume_count INTEGER DEFAULT 0 NOT NULL,
+      workflow_run_number INTEGER,
       created_at INTEGER NOT NULL,
       updated_at INTEGER NOT NULL,
       FOREIGN KEY (project_id) REFERENCES projects(id) ON UPDATE NO ACTION ON DELETE NO ACTION,
@@ -68,6 +72,7 @@ export function bootstrapStagentDatabase(sqlite: Database.Database): void {
       name TEXT NOT NULL,
       definition TEXT NOT NULL,
       status TEXT DEFAULT 'draft' NOT NULL,
+      run_number INTEGER DEFAULT 0 NOT NULL,
       created_at INTEGER NOT NULL,
       updated_at INTEGER NOT NULL,
       FOREIGN KEY (project_id) REFERENCES projects(id) ON UPDATE NO ACTION ON DELETE NO ACTION
@@ -272,6 +277,8 @@ export function bootstrapStagentDatabase(sqlite: Database.Database): void {
 
   // Task source type
   addColumnIfMissing(`ALTER TABLE tasks ADD COLUMN source_type TEXT;`);
+  addColumnIfMissing(`ALTER TABLE workflows ADD COLUMN run_number INTEGER DEFAULT 0 NOT NULL;`);
+  addColumnIfMissing(`ALTER TABLE tasks ADD COLUMN workflow_run_number INTEGER;`);
   addColumnIfMissing(`ALTER TABLE documents ADD COLUMN version INTEGER NOT NULL DEFAULT 1;`);
   addColumnIfMissing(`ALTER TABLE documents ADD COLUMN source TEXT DEFAULT 'upload';`);
   addColumnIfMissing(`ALTER TABLE documents ADD COLUMN conversation_id TEXT REFERENCES conversations(id);`);
@@ -566,6 +573,47 @@ export function bootstrapStagentDatabase(sqlite: Database.Database): void {
     CREATE INDEX IF NOT EXISTS idx_agent_messages_to_status ON agent_messages(to_profile_id, status);
     CREATE INDEX IF NOT EXISTS idx_agent_messages_task ON agent_messages(task_id);
   `);
+
+  // ── Workflow Document Pool ──────────────────────────────────────────
+  sqlite.exec(`
+    CREATE TABLE IF NOT EXISTS workflow_document_inputs (
+      id TEXT PRIMARY KEY NOT NULL,
+      workflow_id TEXT NOT NULL,
+      document_id TEXT NOT NULL,
+      step_id TEXT,
+      created_at INTEGER NOT NULL,
+      FOREIGN KEY (workflow_id) REFERENCES workflows(id) ON UPDATE NO ACTION ON DELETE NO ACTION,
+      FOREIGN KEY (document_id) REFERENCES documents(id) ON UPDATE NO ACTION ON DELETE NO ACTION
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_wdi_workflow ON workflow_document_inputs(workflow_id);
+    CREATE INDEX IF NOT EXISTS idx_wdi_document ON workflow_document_inputs(document_id);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_wdi_workflow_doc_step ON workflow_document_inputs(workflow_id, document_id, step_id);
+
+    CREATE TABLE IF NOT EXISTS schedule_document_inputs (
+      id TEXT PRIMARY KEY NOT NULL,
+      schedule_id TEXT NOT NULL,
+      document_id TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      FOREIGN KEY (schedule_id) REFERENCES schedules(id) ON UPDATE NO ACTION ON DELETE NO ACTION,
+      FOREIGN KEY (document_id) REFERENCES documents(id) ON UPDATE NO ACTION ON DELETE NO ACTION
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_sdi_schedule ON schedule_document_inputs(schedule_id);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_sdi_schedule_doc ON schedule_document_inputs(schedule_id, document_id);
+
+    CREATE TABLE IF NOT EXISTS project_document_defaults (
+      id TEXT PRIMARY KEY NOT NULL,
+      project_id TEXT NOT NULL,
+      document_id TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      FOREIGN KEY (project_id) REFERENCES projects(id) ON UPDATE NO ACTION ON DELETE NO ACTION,
+      FOREIGN KEY (document_id) REFERENCES documents(id) ON UPDATE NO ACTION ON DELETE NO ACTION
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_pdd_project ON project_document_defaults(project_id);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_pdd_project_doc ON project_document_defaults(project_id, document_id);
+  `);
 }
 
 export function hasLegacyStagentTables(sqlite: Database.Database): boolean {

package/src/lib/db/migrations/0016_add_workflow_document_inputs.sql

@@ -0,0 +1,13 @@
+CREATE TABLE IF NOT EXISTS workflow_document_inputs (
+  id TEXT PRIMARY KEY NOT NULL,
+  workflow_id TEXT NOT NULL,
+  document_id TEXT NOT NULL,
+  step_id TEXT,
+  created_at INTEGER NOT NULL,
+  FOREIGN KEY (workflow_id) REFERENCES workflows(id) ON UPDATE NO ACTION ON DELETE NO ACTION,
+  FOREIGN KEY (document_id) REFERENCES documents(id) ON UPDATE NO ACTION ON DELETE NO ACTION
+);
+
+CREATE INDEX IF NOT EXISTS idx_wdi_workflow ON workflow_document_inputs(workflow_id);
+CREATE INDEX IF NOT EXISTS idx_wdi_document ON workflow_document_inputs(document_id);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_wdi_workflow_doc_step ON workflow_document_inputs(workflow_id, document_id, step_id);

package/src/lib/db/migrations/0017_add_document_picker_tables.sql

@@ -0,0 +1,25 @@
+-- Schedule document inputs (context documents for scheduled tasks)
+CREATE TABLE IF NOT EXISTS `schedule_document_inputs` (
+  `id` text PRIMARY KEY NOT NULL,
+  `schedule_id` text NOT NULL,
+  `document_id` text NOT NULL,
+  `created_at` integer NOT NULL,
+  FOREIGN KEY (`schedule_id`) REFERENCES `schedules`(`id`) ON UPDATE NO ACTION ON DELETE NO ACTION,
+  FOREIGN KEY (`document_id`) REFERENCES `documents`(`id`) ON UPDATE NO ACTION ON DELETE NO ACTION
+);
+
+CREATE INDEX IF NOT EXISTS `idx_sdi_schedule` ON `schedule_document_inputs` (`schedule_id`);
+CREATE UNIQUE INDEX IF NOT EXISTS `idx_sdi_schedule_doc` ON `schedule_document_inputs` (`schedule_id`, `document_id`);
+
+-- Project document defaults (auto-attached to new tasks/workflows in project)
+CREATE TABLE IF NOT EXISTS `project_document_defaults` (
+  `id` text PRIMARY KEY NOT NULL,
+  `project_id` text NOT NULL,
+  `document_id` text NOT NULL,
+  `created_at` integer NOT NULL,
+  FOREIGN KEY (`project_id`) REFERENCES `projects`(`id`) ON UPDATE NO ACTION ON DELETE NO ACTION,
+  FOREIGN KEY (`document_id`) REFERENCES `documents`(`id`) ON UPDATE NO ACTION ON DELETE NO ACTION
+);
+
+CREATE INDEX IF NOT EXISTS `idx_pdd_project` ON `project_document_defaults` (`project_id`);
+CREATE UNIQUE INDEX IF NOT EXISTS `idx_pdd_project_doc` ON `project_document_defaults` (`project_id`, `document_id`);

package/src/lib/db/migrations/0018_add_workflow_run_number.sql

@@ -0,0 +1,2 @@
+ALTER TABLE workflows ADD COLUMN run_number INTEGER DEFAULT 0 NOT NULL;
+ALTER TABLE tasks ADD COLUMN workflow_run_number INTEGER;

package/src/lib/db/schema.ts

@@ -37,6 +37,7 @@ export const tasks = sqliteTable(
     sourceType: text("source_type", {
       enum: ["manual", "scheduled", "heartbeat", "workflow"],
     }),
+    workflowRunNumber: integer("workflow_run_number"),
     createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
     updatedAt: integer("updated_at", { mode: "timestamp" }).notNull(),
   },
@@ -59,6 +60,7 @@ export const workflows = sqliteTable("workflows", {
   })
     .default("draft")
     .notNull(),
+  runNumber: integer("run_number").default(0).notNull(),
   createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
   updatedAt: integer("updated_at", { mode: "timestamp" }).notNull(),
 });
@@ -678,6 +680,81 @@ export const agentMessages = sqliteTable(
   ]
 );
 
+// ── Workflow Document Pool ───────────────────────────────────────────
+
+export const workflowDocumentInputs = sqliteTable(
+  "workflow_document_inputs",
+  {
+    id: text("id").primaryKey(),
+    workflowId: text("workflow_id")
+      .references(() => workflows.id)
+      .notNull(),
+    documentId: text("document_id")
+      .references(() => documents.id)
+      .notNull(),
+    /** null = document available to all steps; set = scoped to specific step */
+    stepId: text("step_id"),
+    createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
+  },
+  (table) => [
+    index("idx_wdi_workflow").on(table.workflowId),
+    index("idx_wdi_document").on(table.documentId),
+    uniqueIndex("idx_wdi_workflow_doc_step").on(
+      table.workflowId,
+      table.documentId,
+      table.stepId
+    ),
+  ]
+);
+
+export type WorkflowDocumentInputRow = InferSelectModel<typeof workflowDocumentInputs>;
+
+export const scheduleDocumentInputs = sqliteTable(
+  "schedule_document_inputs",
+  {
+    id: text("id").primaryKey(),
+    scheduleId: text("schedule_id")
+      .references(() => schedules.id)
+      .notNull(),
+    documentId: text("document_id")
+      .references(() => documents.id)
+      .notNull(),
+    createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
+  },
+  (table) => [
+    index("idx_sdi_schedule").on(table.scheduleId),
+    uniqueIndex("idx_sdi_schedule_doc").on(
+      table.scheduleId,
+      table.documentId
+    ),
+  ]
+);
+
+export type ScheduleDocumentInputRow = InferSelectModel<typeof scheduleDocumentInputs>;
+
+export const projectDocumentDefaults = sqliteTable(
+  "project_document_defaults",
+  {
+    id: text("id").primaryKey(),
+    projectId: text("project_id")
+      .references(() => projects.id)
+      .notNull(),
+    documentId: text("document_id")
+      .references(() => documents.id)
+      .notNull(),
+    createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
+  },
+  (table) => [
+    index("idx_pdd_project").on(table.projectId),
+    uniqueIndex("idx_pdd_project_doc").on(
+      table.projectId,
+      table.documentId
+    ),
+  ]
+);
+
+export type ProjectDocumentDefaultRow = InferSelectModel<typeof projectDocumentDefaults>;
+
 // Shared types derived from schema — use these in components instead of `as any`
 export type ProjectRow = InferSelectModel<typeof projects>;
 export type TaskRow = InferSelectModel<typeof tasks>;

package/src/lib/docs/reader.ts

@@ -1,12 +1,11 @@
 import { readFileSync, readdirSync, existsSync } from "fs";
 import { join, basename } from "path";
 import type { DocManifest, ParsedDoc } from "./types";
+import { getAppRoot } from "../utils/app-root";
 
 /** Resolve the docs directory relative to this source file (npx-safe) */
 function docsDir(): string {
-  const dir = import.meta.dirname ?? __dirname;
-  // src/lib/docs/ → project root → docs/
-  return join(dir, "..", "..", "..", "docs");
+  return join(getAppRoot(import.meta.dirname, 3), "docs");
 }
 
 /** Read and parse docs/manifest.json */

package/src/lib/documents/context-builder.ts

@@ -4,8 +4,8 @@
  */
 
 import { db } from "@/lib/db";
-import { documents } from "@/lib/db/schema";
-import { and, eq } from "drizzle-orm";
+import { documents, workflowDocumentInputs } from "@/lib/db/schema";
+import { and, eq, inArray, isNull } from "drizzle-orm";
 import type { DocumentRow } from "@/lib/db/schema";
 
 const MAX_INLINE_TEXT = 10_000;
@@ -114,3 +114,76 @@ export async function buildWorkflowDocumentContext(
     return null;
   }
 }
+
+/**
+ * Build document context from the workflow document pool (junction table).
+ * Queries workflow_document_inputs for documents bound to this workflow,
+ * optionally scoped to a specific step. Returns null if no pool documents.
+ *
+ * Includes both workflow-level bindings (stepId=null) and step-specific bindings.
+ */
+export async function buildPoolDocumentContext(
+  workflowId: string,
+  stepId?: string
+): Promise<string | null> {
+  try {
+    // Get workflow-level (stepId=null) bindings — available to all steps
+    const globalBindings = await db
+      .select({ documentId: workflowDocumentInputs.documentId })
+      .from(workflowDocumentInputs)
+      .where(
+        and(
+          eq(workflowDocumentInputs.workflowId, workflowId),
+          isNull(workflowDocumentInputs.stepId)
+        )
+      );
+
+    // If a specific step, also get step-scoped bindings
+    let stepBindings: { documentId: string }[] = [];
+    if (stepId) {
+      stepBindings = await db
+        .select({ documentId: workflowDocumentInputs.documentId })
+        .from(workflowDocumentInputs)
+        .where(
+          and(
+            eq(workflowDocumentInputs.workflowId, workflowId),
+            eq(workflowDocumentInputs.stepId, stepId)
+          )
+        );
+    }
+
+    // Deduplicate document IDs
+    const docIdSet = new Set<string>();
+    for (const b of [...globalBindings, ...stepBindings]) {
+      docIdSet.add(b.documentId);
+    }
+
+    if (docIdSet.size === 0) return null;
+
+    const docs = await db
+      .select()
+      .from(documents)
+      .where(inArray(documents.id, [...docIdSet]));
+
+    if (docs.length === 0) return null;
+
+    const sections = docs.map((doc, i) => formatDocument(doc, i));
+    let result = sections.join("\n\n");
+
+    if (result.length > MAX_WORKFLOW_DOC_CONTEXT) {
+      result = result.slice(0, MAX_WORKFLOW_DOC_CONTEXT);
+      result += `\n\n(Pool document context truncated at ${MAX_WORKFLOW_DOC_CONTEXT} chars — use Read tool for full content)`;
+    }
+
+    return [
+      "--- Workflow Pool Documents ---",
+      "",
+      result,
+      "",
+      "--- End Workflow Pool Documents ---",
+    ].join("\n");
+  } catch (error) {
+    console.error("[context-builder] Failed to build pool document context:", error);
+    return null;
+  }
+}