indusagi-coding-agent 0.2.5 → 0.2.9

package/src/boot/upgrade/upgrades.ts

@@ -0,0 +1,289 @@
+/**
+ * Upgrade registry — the ordered, idempotent catalog of one-time profile
+ * migrations.
+ *
+ * This module replaces a bag of magic constants and inlined `try/catch`
+ * migration blocks with a *registry*: an explicit, ordered list of named
+ * {@link Upgrade} steps. Each step owns a stable {@link Upgrade.id}, a one-line
+ * {@link Upgrade.describe}, and an idempotent {@link Upgrade.apply}. The driver
+ * ({@link "./apply"}) folds over the list in order, recording the ids it has run
+ * in a marker file so a step never runs twice — re-running the whole registry on
+ * an already-upgraded profile is a no-op.
+ *
+ * Idempotence contract (every step must honor it):
+ *   - Detect "already done" cheaply and return early without side effects.
+ *   - Treat a *missing* source (the thing being migrated from) as success — the
+ *     profile is either fresh or already past this point.
+ *   - Never destroy data: relocations move-or-skip, never overwrite a live
+ *     destination; the legacy source is suffixed, not deleted.
+ *
+ * The seeded steps fold the legacy on-disk layout into the current one:
+ *   1. {@link foldCredentials}   — legacy split auth → one secure `auth.json`.
+ *   2. {@link reshelveTranscripts} — loose session files → per-cwd `sessions/`.
+ *   3. {@link relocateBinaries}  — managed `fd`/`rg` helpers → the `bin/` dir.
+ *   4. {@link renamePromptDir}   — legacy `commands/` dir → `prompts/`.
+ *
+ * Session-directory encoding note: step 2 must place a transcript under the
+ * *same* per-cwd directory name the framework's session manager would compute.
+ * The framework publishes no standalone encoder for that name (the encoding is
+ * private to its session manager), so this module uses a clearly-named local
+ * helper, {@link projectTranscriptDirName}, rather than re-deriving the
+ * framework's private per-cwd directory encoding. If the framework later exports
+ * an encoder, swap the helper for the import without touching the step logic.
+ */
+import { promises as fs, constants as fsConstants } from "node:fs";
+import { join, dirname, basename } from "node:path";
+import type { Workspace } from "../contract.js";
+
+/**
+ * One ordered, idempotent profile-layout upgrade.
+ *
+ * An upgrade is pure data plus one async effect. The registry order is the
+ * apply order; the {@link id} is the durable key recorded in the marker file
+ * once {@link apply} completes, so it must be stable across releases (renaming an
+ * id re-runs the step). {@link apply} must be safe to invoke against a profile in
+ * any state — fresh, partially-migrated, or fully-migrated.
+ */
+export interface Upgrade {
+  /** Durable identifier recorded once this step has run. Never rename. */
+  readonly id: string;
+  /** One-line human summary for logs and `--verbose` output. */
+  readonly describe: string;
+  /**
+   * Perform the upgrade against the resolved {@link Workspace}. Must be
+   * idempotent: detect "already applied" and return without side effects.
+   *
+   * @param ws The resolved, absolute on-disk layout.
+   */
+  apply(ws: Workspace): Promise<void>;
+}
+
+const SECURE_FILE_MODE = 384;
+const RETIRED_SUFFIX = ".retired";
+
+async function pathExists(target: string): Promise<boolean> {
+  try {
+    await fs.access(target, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isDirectory(target: string): Promise<boolean> {
+  try {
+    return (await fs.stat(target)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function isFile(target: string): Promise<boolean> {
+  try {
+    return (await fs.stat(target)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function readJsonOrUndefined(target: string): Promise<unknown> {
+  try {
+    return JSON.parse(await fs.readFile(target, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+async function writeJsonWithMode(target: string, value: unknown, mode: number): Promise<void> {
+  await fs.mkdir(dirname(target), { recursive: true });
+  await fs.writeFile(target, `${JSON.stringify(value, null, 2)}\n`, { mode });
+  await fs.chmod(target, mode);
+}
+
+async function relocateWithoutClobber(from: string, into: string): Promise<boolean> {
+  if (!(await pathExists(from))) return false;
+  if (await pathExists(into)) return false;
+  await fs.mkdir(dirname(into), { recursive: true });
+  await fs.rename(from, into);
+  return true;
+}
+
+/**
+ * Compute the per-project transcript sub-directory *name* for a working
+ * directory.
+ *
+ * This deliberately does not reproduce the framework session manager's private
+ * encoding character-for-character; the framework exposes no public encoder to
+ * import, so this is the documented local fallback. It produces a single,
+ * filesystem-safe directory leaf that is stable for a given absolute `cwd`:
+ * path separators, drive colons, and any other non-portable characters collapse
+ * to a single token, and a short content hash is appended so two distinct paths
+ * that happen to fold to the same token never collide.
+ *
+ * The output is used only when *relocating a loose legacy transcript* into the
+ * sessions tree; live sessions are always created by the framework itself, so
+ * this helper never competes with the framework for the canonical name.
+ *
+ * @param cwd Absolute working directory the transcript belongs to.
+ * @returns A safe directory leaf such as `proj-Users-me-app-1a2b3c4d`.
+ */
+export function projectTranscriptDirName(cwd: string): string {
+  const trimmed = cwd.trim() || "root";
+  const folded = trimmed.split(/[^A-Za-z0-9]+/u).filter((segment) => segment.length > 0).join("-");
+  const token = folded.length > 0 ? folded : "root";
+  return `proj-${token}-${shortPathHash(trimmed)}`;
+}
+
+function shortPathHash(input: string): string {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+
+const LEGACY_OAUTH_FILE = "oauth.json";
+const LEGACY_SETTINGS_FILE = "settings.json";
+const MANAGED_HELPER_BASENAMES = ["fd", "rg", "fd.exe", "rg.exe"];
+const LEGACY_PROMPTS_DIRNAME = "commands";
+
+/**
+ * Fold a legacy split credential layout — a standalone `oauth.json` plus an
+ * `apiKeys` block embedded in `settings.json` — into the single consolidated
+ * `auth.json`, written with owner-only (`0o600`-equivalent) permissions.
+ *
+ * Idempotent: if `auth.json` already exists, nothing is touched. After a
+ * successful fold the legacy `oauth.json` is suffixed (`oauth.json.retired`) and
+ * the `apiKeys` block is removed from `settings.json`, so a second run finds no
+ * legacy sources and the existing `auth.json` short-circuits it regardless.
+ */
+export const foldCredentials: Upgrade = {
+  id: "fold-credentials-into-secure-auth-file",
+  describe: "Consolidate legacy oauth.json + settings.apiKeys into a 0600 auth.json",
+  async apply(ws) {
+    if (await pathExists(ws.authPath)) return;
+    const legacyOauthPath = join(ws.profileDir, LEGACY_OAUTH_FILE);
+    const legacySettingsPath = join(ws.profileDir, LEGACY_SETTINGS_FILE);
+    const oauth = await readJsonOrUndefined(legacyOauthPath);
+    const settings = await readJsonOrUndefined(legacySettingsPath);
+    const apiKeys = (settings as { apiKeys?: unknown } | undefined)?.apiKeys;
+    const haveOauth = oauth !== undefined && Object.keys(oauth as object).length > 0;
+    const haveApiKeys = apiKeys !== undefined && Object.keys(apiKeys as object).length > 0;
+    if (!haveOauth && !haveApiKeys) return;
+    const folded: Record<string, unknown> = {};
+    if (haveOauth) folded.oauth = oauth;
+    if (haveApiKeys) folded.apiKeys = apiKeys;
+    await writeJsonWithMode(ws.authPath, folded, SECURE_FILE_MODE);
+    if (await isFile(legacyOauthPath)) {
+      const retiredOauth = `${legacyOauthPath}${RETIRED_SUFFIX}`;
+      if (!(await pathExists(retiredOauth))) {
+        await fs.rename(legacyOauthPath, retiredOauth);
+      }
+    }
+    if (haveApiKeys && settings && (await isFile(legacySettingsPath))) {
+      const { apiKeys: _migrated, ...remaining } = settings as { apiKeys?: unknown } & Record<string, unknown>;
+      await fs.writeFile(legacySettingsPath, `${JSON.stringify(remaining, null, 2)}\n`);
+    }
+  },
+};
+
+async function readTranscriptHeader(filePath: string): Promise<{ type?: string; cwd?: string } | undefined> {
+  try {
+    const content = await fs.readFile(filePath, "utf8");
+    const firstLine = content.split("\n", 1)[0]?.trim();
+    if (!firstLine) return undefined;
+    return JSON.parse(firstLine);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Relocate loose `*.jsonl` transcripts that were written directly under the
+ * profile root (a legacy layout) into the structured per-cwd sessions tree:
+ * `sessions/<projectDirName>/<file>`.
+ *
+ * A loose file is recognized as a transcript by a first-line header of
+ * `type: "session"`. The destination project directory is derived from the
+ * header's recorded `cwd` via {@link projectTranscriptDirName} (the framework
+ * owns no public encoder to delegate to — see this module's header). Each move
+ * is skip-on-clobber, so re-running never overwrites an already-relocated
+ * transcript, and once no loose transcripts remain the step is a pure no-op.
+ */
+export const reshelveTranscripts: Upgrade = {
+  id: "reshelve-loose-transcripts-into-sessions-dir",
+  describe: "Move loose session .jsonl files under the profile root into sessions/<cwd>/",
+  async apply(ws) {
+    let entries: string[];
+    try {
+      entries = await fs.readdir(ws.profileDir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.endsWith(".jsonl")) continue;
+      const loosePath = join(ws.profileDir, entry);
+      if (!(await isFile(loosePath))) continue;
+      const header = await readTranscriptHeader(loosePath);
+      if (header?.type !== "session") continue;
+      const projectDir = projectTranscriptDirName(header.cwd ?? ws.profileDir);
+      const destination = join(ws.sessionsDir, projectDir, basename(loosePath));
+      await relocateWithoutClobber(loosePath, destination);
+    }
+  },
+};
+
+/**
+ * Relocate the managed native helper binaries (`fd`, `rg`, and their Windows
+ * `.exe` forms) from the legacy `tools/` directory into the canonical managed
+ * `bin/` directory ({@link Workspace.binDir}).
+ *
+ * Each binary is moved skip-on-clobber and independently, so a partially-moved
+ * state self-heals on the next run and an already-relocated layout (or a fresh
+ * install with no legacy `tools/`) is a no-op.
+ */
+export const relocateBinaries: Upgrade = {
+  id: "relocate-managed-helper-binaries-to-bin",
+  describe: "Move managed fd/rg helper binaries from the legacy tools/ dir into bin/",
+  async apply(ws) {
+    const legacyToolsDir = join(ws.profileDir, "tools");
+    if (!(await isDirectory(legacyToolsDir))) return;
+    for (const name of MANAGED_HELPER_BASENAMES) {
+      const from = join(legacyToolsDir, name);
+      if (!(await isFile(from))) continue;
+      await relocateWithoutClobber(from, join(ws.binDir, name));
+    }
+  },
+};
+
+/**
+ * Rename the legacy command-template directory (`commands/`) to the current
+ * prompt-template directory ({@link Workspace.promptsDir}).
+ *
+ * Idempotent: if the destination already exists the rename is skipped (the
+ * profile is already on the current layout), and if the legacy directory is
+ * absent there is nothing to do. The rename is whole-directory and
+ * non-destructive — a live `prompts/` is never replaced.
+ */
+export const renamePromptDir: Upgrade = {
+  id: "rename-legacy-commands-dir-to-prompts",
+  describe: "Rename the legacy commands/ template directory to prompts/",
+  async apply(ws) {
+    const legacyPromptsDir = join(ws.profileDir, LEGACY_PROMPTS_DIRNAME);
+    if (!(await isDirectory(legacyPromptsDir))) return;
+    await relocateWithoutClobber(legacyPromptsDir, ws.promptsDir);
+  },
+};
+
+/**
+ * The ordered list of upgrades. Apply order is array order; ids are the durable
+ * marker keys. Append new steps to the end — never reorder or rename existing
+ * ids, as that would re-run already-applied migrations.
+ */
+export const UPGRADES: readonly Upgrade[] = [
+  foldCredentials,
+  reshelveTranscripts,
+  relocateBinaries,
+  renamePromptDir,
+];

package/src/briefing/compose.ts

@@ -0,0 +1,150 @@
+import type {
+  AgentTool,
+  Briefing,
+  BriefingContext,
+  BriefingInputs,
+  BriefingSection,
+} from "./contract.js";
+
+export const TOOL_SUMMARIES: Readonly<Record<string, string>> = {
+  read: "Open a file's contents for inspection.",
+  write: "Create a new file or overwrite an existing one wholesale.",
+  edit: "Apply a precise in-place change by matching exact existing text.",
+  bash: "Run a shell command in the workspace.",
+  grep: "Search file contents by pattern across the tree.",
+  find: "Locate files and directories by name or glob.",
+  ls: "List the entries of a directory.",
+  task: "Hand a self-contained sub-task to a delegate agent.",
+  todoread: "Read back the current task checklist.",
+  todowrite: "Record or revise the task checklist.",
+  webfetch: "Retrieve and read the contents of a URL.",
+  websearch: "Query the web for current information.",
+};
+
+export function joinBlocks(parts: readonly string[]): string {
+  return parts.filter((part) => part.trim().length > 0).join("\n\n");
+}
+
+export function bullets(lines: readonly string[]): string {
+  return lines.map((line) => `- ${line}`).join("\n");
+}
+
+export function escapeXml(value: string): string {
+  let out = "";
+  for (const ch of value) {
+    const escaped = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[ch];
+    out += escaped ?? ch;
+  }
+  return out;
+}
+
+export function hasTool(ctx: BriefingContext, id: string): boolean {
+  return (ctx.tools ?? []).some((tool: AgentTool) => tool.name === id);
+}
+
+export function hasToolPrefix(ctx: BriefingContext, prefix: string): boolean {
+  return (ctx.tools ?? []).some((tool: AgentTool) => tool.name.startsWith(prefix));
+}
+
+export function describeTool(tool: AgentTool): string {
+  const summary = TOOL_SUMMARIES[tool.name] ?? tool.description?.trim() ?? "";
+  return summary.length > 0 ? `\`${tool.name}\` — ${summary}` : `\`${tool.name}\``;
+}
+
+export const ROLE_SECTION: BriefingSection = {
+  id: "role",
+  render: () => joinBlocks([
+    "You are a terminal-based software engineering assistant. You operate inside a real workspace and make progress by reading code, running commands, and editing files directly — not by describing what someone else should do.",
+    "Work toward the user's actual goal. Take the initiative to gather the context you need, but stay within the scope of what was asked: do not redesign, rename, or refactor beyond the request unless the user invites it.",
+  ]),
+};
+
+export const TOOLS_SECTION: BriefingSection = {
+  id: "tools", title: "Tools",
+  applies: (ctx: BriefingContext) => (ctx.tools ?? []).length > 0,
+  render: (ctx: BriefingContext) => joinBlocks(["# Tools", "These capabilities are available to you this turn. Reach for the most specific one for the job.", bullets((ctx.tools ?? []).map(describeTool))]),
+};
+
+export const GUIDELINES_SECTION: BriefingSection = {
+  id: "guidelines", title: "Working guidance",
+  render(ctx: BriefingContext) {
+    const items: string[] = [];
+    if (hasTool(ctx, "read")) items.push("Always inspect a file with the reader before you change it. Do not shell out to `cat`, `head`, or `sed` to view a file when the reader is available.");
+    if (hasTool(ctx, "edit")) items.push("For a targeted change, prefer the editor: it replaces an exact span of existing text, so the old text you supply must match the file byte-for-byte.");
+    if (hasTool(ctx, "write")) items.push("Reserve the writer for creating a new file or replacing one in full; for anything smaller, edit in place rather than rewriting the whole file.");
+    if (hasTool(ctx, "grep") || hasTool(ctx, "find") || hasTool(ctx, "ls")) items.push("Explore the tree with the dedicated search and listing tools rather than shell equivalents — they are quicker and already skip ignored paths.");
+    if (hasTool(ctx, "bash")) items.push("Use the shell for builds, tests, and other commands that no purpose-built tool covers. Keep commands scoped and avoid destructive operations unless the user asked for them.");
+    items.push("Keep your replies short and to the point. Lead with the result; add only the explanation the user needs to act on it.");
+    items.push("When a change is non-trivial, verify it — run the build or the relevant tests — before you report it as done.");
+    return joinBlocks(["# Working guidance", bullets(items)]);
+  },
+};
+
+export const TASK_SECTION: BriefingSection = {
+  id: "tasks", title: "Task tracking",
+  applies: (ctx: BriefingContext) => hasTool(ctx, "todowrite") || hasTool(ctx, "todoread"),
+  render: () => joinBlocks(["# Task tracking", "For work that spans several steps, maintain a checklist with the task tools. Break the job into concrete items, mark exactly one in progress at a time, and tick items off as you finish them so the user can follow along."]),
+};
+
+export const SUBAGENTS_SECTION: BriefingSection = {
+  id: "subagents", title: "Delegates",
+  applies: (ctx: BriefingContext) => (ctx.subagents ?? []).length > 0,
+  render: (ctx: BriefingContext) => joinBlocks(["# Delegates", "You can offload a focused, self-contained piece of work to one of these delegates with the task tool. Hand off when a sub-problem is well-scoped enough to be solved without your full conversation context.", bullets((ctx.subagents ?? []).map((subagent) => `**${subagent.name}** — ${subagent.purpose}.${subagent.when ? ` Use it when ${subagent.when}` : ""}`))]),
+};
+
+export const COORDINATOR_SECTION: BriefingSection = {
+  id: "coordinator", title: "Orchestrating sub-agents", applies: (ctx: BriefingContext) => hasTool(ctx, "task"),
+  render: () => joinBlocks([
+    "# Orchestrating sub-agents",
+    "When work is naturally parallel or context-heavy, you can offload bounded pieces to sub-agents via the `task` tool. Sub-agents execute autonomously and return one report.",
+    bullets([
+      "Delegate when a sub-problem is well-scoped enough to solve without your full conversation context, when multiple independent investigations can run in parallel, or when research would otherwise fill your context with raw output you won't need again.",
+      "Do NOT delegate trivial work, questions you can answer directly, or one quick file reads or shell commands — sub-agents add latency and lose the parent's accumulated reasoning.",
+      "Sub-agents receive a focused authoring tool deck: read, write, edit, grep, find, ls, bash, todoread, todowrite, webfetch, websearch, workflow, and structured_output. They do NOT see your conversation history and cannot spawn further sub-agents.",
+      "Each sub-agent runs its own complete tool loop and returns one final report. There is no built-in continue/cancel mechanism — plan the full objective upfront.",
+      "If a sub-agent fails or produces wrong output, do not retry the same task with the same arguments. Analyze the failure, adjust your approach, and spawn a fresh sub-agent with a refined objective.",
+    ]),
+    "# Writing sub-agent objectives", "Workers cannot see your conversation. Every objective must be self-contained with everything the worker needs.",
+    bullets(["Include file paths, line numbers, error messages — workers start fresh and need complete context.", "State what 'done' looks like (commit hash, test result, report format).", "For implementation: 'Run relevant tests and typecheck, then commit your changes and report the hash.' — workers self-verify before reporting done.", "For research: 'Report findings — do not modify files.'", "Be precise about git operations — specify branch names, commit hashes, draft vs ready, reviewers.", "For implementation: 'Fix the root cause, not the symptom.' — guide workers toward durable fixes.", "For verification: 'Prove the code works, don't just confirm it exists.' and 'Try edge cases and error paths — don't just re-run what the implementation worker ran.'"]),
+    "# Phases for complex work", bullets(["Research — sub-agents (parallel). Investigate the codebase, find files, understand the problem. Each sub-agent reports findings without modifying files.", "Synthesis — you (parent). Read the findings. Understand the problem. Craft a concrete implementation spec with file paths, line numbers, and exact changes.", "Implementation — sub-agents. Make targeted changes per the spec. Run tests and typecheck. Commit. Report the hash.", "Verification — sub-agents. Test that the changes work end-to-end. Run the original failing scenario. Prove the fix, don't rubber-stamp."]),
+    "# Parallelism", "Launch independent sub-agents concurrently whenever possible. Don't serialize work that can run simultaneously. When researching, cover multiple angles in parallel — issue multiple task tool calls in a single message.",
+  ]),
+};
+
+export const PLAN_SECTION: BriefingSection = {
+  id: "plan-mode", title: "Plan mode", applies: (ctx: BriefingContext) => hasTool(ctx, "enter_plan_mode") || hasTool(ctx, "exit_plan_mode"),
+  render: () => joinBlocks(["# Plan mode", bullets(["For a task that needs investigation before any change, call `enter_plan_mode` first. That switches you into a read-only research phase: you may read, search, and inspect, but every file-mutating and shell tool is blocked until you leave.", "While in plan mode, gather all the context you need and draft a concrete plan. Do not try to edit files or run commands — those calls are rejected with a steering message.", "When the plan is ready, call `exit_plan_mode` with the full plan text. The user reviews it and either approves (you leave plan mode and carry the plan out) or rejects (you stay in plan mode to revise and re-propose). Use it to ask permission to start, not to do the work."])]),
+};
+
+function taskSection(id: string, title: string, blocks: string[]): BriefingSection {
+  return { id, title, applies: (ctx: BriefingContext) => hasTool(ctx, "task"), render: () => joinBlocks([`# ${title}`, ...blocks]) };
+}
+
+export const PLAN_AGENT_SECTION = taskSection("plan-agent", "Plan sub-agent", ["For non-trivial implementation work you can delegate the entire planning phase to a read-only sub-agent that returns a structured plan:", "`task({ agent: \"plan\", objective: \"Plan the implementation of <feature>\" })`", "The plan sub-agent explores the codebase with read, grep, find, and ls; identifies existing patterns; designs an implementation approach with trade-offs; and returns a step-by-step plan with a 'Critical Files for Implementation' list. The sub-agent operates read-only — it cannot write, edit, or run state-changing commands. Use it before you start implementing when the scope is unclear or the change spans multiple files."]);
+export const VERIFICATION_AGENT_SECTION = taskSection("verification-agent", "Verification sub-agent", ["For non-trivial implementation work, delegate independent verification to a dedicated sub-agent that adversarially tries to break the change:", "`task({ agent: \"verification\", objective: \"Verify the implementation of <feature>. Files changed: <list>. Approach: <summary>.\" })`", "The verification sub-agent runs the build, executes the test suite, runs linters/type-checkers, exercises edge cases (concurrency, boundary values, idempotency, orphan operations), and returns a structured verdict. It operates read-only on the project (temp test scripts allowed), ends with `VERDICT: PASS|FAIL|PARTIAL`, and never rubber-stamps work without running commands. Use it after implementation completes, before reporting success to the user."]);
+export const EXPLORE_AGENT_SECTION = taskSection("explore-agent", "Explore sub-agent", ["For codebase questions that require fast parallel searching across many files, delegate to a dedicated read-only search sub-agent:", "`task({ agent: \"explore\", objective: \"Find all usages of <API>. Thoroughness: <quick|medium|very thorough>.\" })`", "The explore sub-agent runs file searches (find, grep), reads targeted files, and reports findings without modifying anything. It uses parallel tool calls for speed and adapts to your thoroughness request. Use it for broad codebase discovery, finding call sites, or answering 'how does X work in this repo?' questions."]);
+
+export const SECURITY_REVIEW_SECTION: BriefingSection = { id: "security-review", title: "Security review", render: () => joinBlocks(["# Security review", "For non-trivial PRs, perform a focused security review with a senior security engineer mindset. Apply these filters:", bullets(["Only flag issues where you're >80% confident of actual exploitability.", "Skip theoretical issues, style concerns, and low-impact findings.", "Exclude DoS, secrets-on-disk, rate limiting, library version mismatches.", "Output: file, line, severity (HIGH/MEDIUM/LOW), category, description, exploit scenario, recommendation."]), "The full security-review prompt (with confidence scoring and 17 hard exclusions) is available as a constant in the bundled files for use via the task tool."]) };
+export const CONNECTORS_SECTION: BriefingSection = { id: "connectors", title: "Connectors", applies: (ctx: BriefingContext) => hasToolPrefix(ctx, "connector_") || hasToolPrefix(ctx, "saas_"), render: () => joinBlocks(["# Connectors", bullets(["When a task needs an external service (issue trackers, calendars, docs, and the like), prefer the connector tools over scraping or guessing.", "Confirm the connection is authorized before you rely on it, and surface a clear next step if it is not.", "Page through large result sets deliberately rather than assuming the first response is complete."])]) };
+export const PROJECT_CONTEXT_SECTION: BriefingSection = { id: "project-context", title: "Project context", applies: (ctx: BriefingContext) => (ctx.contextDocs ?? []).length > 0, render: (ctx: BriefingContext) => joinBlocks(["# Project context", "The following project documents describe conventions for this repository. Treat them as standing instructions.", ...(ctx.contextDocs ?? []).map((doc) => `## ${doc.path}\n\n${doc.body.trim()}`)]) };
+export const SKILLS_SECTION: BriefingSection = { id: "skills", title: "Skills", applies: (ctx: BriefingContext) => (ctx.skills ?? []).length > 0, render: (ctx: BriefingContext) => joinBlocks(["# Skills", "Each skill below is a set of task-specific instructions stored on disk. When a task lines up with a skill's description, load its file with the reader and follow it. Paths a skill mentions are relative to that skill's own directory.", `<available_skills>\n${(ctx.skills ?? []).map((card) => `  <skill>\n    <name>${escapeXml(card.name)}</name>\n    <description>${escapeXml(card.description)}</description>\n    <location>${escapeXml(card.location)}</location>\n  </skill>`).join("\n")}\n</available_skills>`]) };
+export const FOOTER_SECTION: BriefingSection = { id: "footer", render: (ctx: BriefingContext) => { const lines: string[] = []; const where = ctx.cwd ?? ctx.workspace; if (where) lines.push(`Working directory: ${where}`); lines.push(`Current time: ${(ctx.now ?? new Date()).toISOString()}`); return lines.join("\n"); } };
+
+export const BRIEFING_SECTIONS: Briefing = [ROLE_SECTION, TOOLS_SECTION, GUIDELINES_SECTION, TASK_SECTION, SUBAGENTS_SECTION, COORDINATOR_SECTION, PLAN_SECTION, PLAN_AGENT_SECTION, VERIFICATION_AGENT_SECTION, EXPLORE_AGENT_SECTION, SECURITY_REVIEW_SECTION, CONNECTORS_SECTION, PROJECT_CONTEXT_SECTION, SKILLS_SECTION, FOOTER_SECTION];
+
+export function isInputs(value: BriefingContext | BriefingInputs): value is BriefingInputs {
+  return "sections" in value && "context" in value;
+}
+
+export function composeBriefing(input: BriefingContext | BriefingInputs): string {
+  const inputs = isInputs(input) ? input : { sections: BRIEFING_SECTIONS, context: input };
+  const rendered: string[] = [];
+  if (inputs.prelude?.trim()) rendered.push(inputs.prelude.trim());
+  for (const section of inputs.sections) {
+    if (section.applies && !section.applies(inputs.context)) continue;
+    const fragment = section.render(inputs.context).trim();
+    if (fragment) rendered.push(fragment);
+  }
+  if (inputs.append?.trim()) rendered.push(inputs.append.trim());
+  return joinBlocks(rendered);
+}

package/src/briefing/context-docs.ts

@@ -0,0 +1,19 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, extname, isAbsolute, join, parse, resolve } from "node:path";
+import type { ContextDoc } from "./contract.js";
+
+export interface GatherContextDocsOptions { readonly maxImportDepth?: number; readonly maxBytesPerDoc?: number; }
+export const DEFAULT_MAX_IMPORT_DEPTH = 5;
+export const DEFAULT_MAX_BYTES_PER_DOC = 40_000;
+export const CANDIDATE_FILES = ["AGENTS.md", "CLAUDE.md", "INDUSAGI.md", "CLAUDE.local.md", "AGENTS.local.md", join(".indusagi", "CLAUDE.md"), join(".claude", "CLAUDE.md")];
+export const TEXT_FILE_EXTENSIONS = new Set([".md", ".markdown", ".txt", ".text", ".json", ".jsonc", ".yaml", ".yml", ".toml", ".xml", ".csv", ".html", ".htm", ".css", ".js", ".ts", ".tsx", ".jsx", ".mjs", ".cjs", ".mts", ".cts", ".py", ".rb", ".go", ".rs", ".sh", ".env"]);
+export const IMPORT_REGEX = /(?:^|\s)@((?:[^\s\\]|\\ )+)/g;
+
+export function shortenPath(path: string, cwd: string, home: string): string { if (cwd && path.startsWith(cwd)) { const rest = path.slice(cwd.length).replace(/^[/\\]+/, ""); return rest ? `./${rest}` : "."; } return home && path.startsWith(home) ? `~${path.slice(home.length)}` : path; }
+export function dirChain(cwd: string): string[] { const chain: string[] = []; let current = cwd; for (let i = 0; i < 256; i++) { chain.push(current); const parent = dirname(current); if (parent === current || current === parse(current).root) break; current = parent; } return chain.reverse(); }
+export function safeRealpath(path: string): string { try { return realpathSync(path); } catch { return path; } }
+export function isTextFile(path: string): boolean { const extension = extname(path).toLowerCase(); return !extension || TEXT_FILE_EXTENSIONS.has(extension); }
+export function readFileBody(path: string): string | null { if (!existsSync(path)) return null; try { const body = readFileSync(path, "utf8").trim(); return body || null; } catch { return null; } }
+export function extractImports(body: string, baseDir: string, home: string): string[] { const out: string[] = []; IMPORT_REGEX.lastIndex = 0; let match: RegExpExecArray | null; while ((match = IMPORT_REGEX.exec(body))) { let spec = match[1]; if (!spec) continue; const hash = spec.indexOf("#"); if (hash >= 0) spec = spec.slice(0, hash); spec = spec.replace(/\\ /g, " ").trim(); if (!spec) continue; const absolute = spec.startsWith("~/") ? join(home, spec.slice(2)) : isAbsolute(spec) ? spec : resolve(baseDir, spec); if (isTextFile(absolute)) out.push(absolute); } return out; }
+export function loadDocTree(path: string, cwd: string, home: string, seen: Set<string>, depth: number, maxDepth: number, maxBytes: number, out: ContextDoc[]): void { const real = safeRealpath(path); if (seen.has(real)) return; seen.add(real); const body = readFileBody(path); if (body === null) return; out.push({ path: shortenPath(path, cwd, home), body: body.length > maxBytes ? body.slice(0, maxBytes) : body }); if (depth >= maxDepth) return; for (const child of extractImports(body, dirname(path), home)) loadDocTree(child, cwd, home, seen, depth + 1, maxDepth, maxBytes, out); }
+export function gatherContextDocs(cwd: string, home: string, opts?: GatherContextDocsOptions): readonly ContextDoc[] { const out: ContextDoc[] = []; try { const seen = new Set<string>(); const roots = dirChain(cwd); if (home) roots.push(home); for (const dir of roots) for (const name of CANDIDATE_FILES) loadDocTree(join(dir, name), cwd, home, seen, 0, opts?.maxImportDepth ?? DEFAULT_MAX_IMPORT_DEPTH, opts?.maxBytesPerDoc ?? DEFAULT_MAX_BYTES_PER_DOC, out); } catch { return out; } return out; }