@howarewoo/pi-subagents 0.0.0-stage → 0.1.1

package/src/profile-viewer.ts

@@ -0,0 +1,175 @@
+import type { Skill, Theme } from "@earendil-works/pi-coding-agent";
+import {
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+  type Component,
+  type KeybindingsManager,
+} from "@earendil-works/pi-tui";
+import { safe } from "./thread.ts";
+import { bundledProfiles, resolveProfile, type Profile } from "./profiles.ts";
+
+export const profileToolPolicy =
+  "Profile tools are maximum allowlists, not requirements. Admission intersects callable parent builtins without activating tools. Command context has no callable-tool dispatcher: effective tools are unknown here. Active declarations are not proof of callability. General inherits available parent skills and callable builtins within its ceiling, not parent instructions/history; only operator-reviewed leaf tools may be forwarded and all require a writer lease. Leaf grants assert trusted code, not a sandbox. Inspect task snapshot tools, leafTools, skills and capabilityDenials for admitted grants.";
+
+/** Resolve through the same trust/config/skill validation boundary used by admission. */
+export async function resolvedProfiles(
+  cwd: string,
+  trusted: boolean,
+  operatorDir?: string,
+  availableSkills: readonly Skill[] = [],
+): Promise<Profile[]> {
+  return Promise.all(
+    bundledProfiles().map(
+      async ({ name }) =>
+        (await resolveProfile(name, cwd, trusted, operatorDir, availableSkills)).profile,
+    ),
+  );
+}
+
+function details(profile: Profile): string[] {
+  const list = (items: readonly string[] | undefined) =>
+    items?.length ? items.join(", ") : "none";
+  const known = new Set([
+    "name",
+    "description",
+    "prompt",
+    "tools",
+    "skills",
+    "leafTools",
+    "spawn",
+    "coordination",
+    "models",
+    "model",
+    "prewalk",
+  ]);
+  return [
+    profile.name,
+    "Description",
+    profile.description,
+    "Prompt",
+    profile.prompt,
+    `Tools ceiling: ${list(profile.tools)}`,
+    "Callable tools: unknown in command context; inspect admitted task tools.",
+    `Skills (exact paths): ${list(profile.skills)}`,
+    ...(profile.name === "general"
+      ? [
+          "Inheritance: available parent skills and callable builtins; no parent instructions/history.",
+        ]
+      : []),
+    `Reviewed leaf ceiling: ${list(profile.leafTools)} (writer lease; trusted code, not sandboxed)`,
+    `Spawn ceiling: ${list(profile.spawn)}`,
+    `Coordination: ${list(profile.coordination)}`,
+    `Model default: ${profile.model ? JSON.stringify(profile.model) : "selected parent model"}`,
+    `Models grant: ${profile.models === undefined ? "no explicit override grant" : JSON.stringify(profile.models)}`,
+    `Prewalk: ${profile.prewalk ? JSON.stringify(profile.prewalk) : "off"}`,
+    ...Object.entries(profile)
+      .filter(([key]) => !known.has(key))
+      .map(([key, value]) => `${key}: ${JSON.stringify(value)}`),
+    "Admission also applies parent/ancestry, model availability, capacity and writer checks. This viewer grants nothing.",
+  ];
+}
+
+/** Read-only snapshot consumer; no fixed role count or policy defaults in the renderer. */
+export function createProfileViewer(
+  profiles: readonly Profile[],
+  theme: Pick<Theme, "fg" | "style"> & { colors: Pick<Theme["colors"], "customMessageBg"> },
+  keys: Pick<KeybindingsManager, "matches" | "getKeys">,
+  requestRender: () => void,
+  done: () => void,
+  availableRows: () => number,
+): Component {
+  let selected = 0;
+  let offset = 0;
+  let viewport = 1;
+  let maximum = 0;
+  const cell = (text: string, width: number) => {
+    const clipped = truncateToWidth(text, width);
+    return clipped + " ".repeat(Math.max(0, width - visibleWidth(clipped)));
+  };
+  return {
+    render(width) {
+      width = Math.max(0, width);
+      const height = Math.max(1, Math.floor(availableRows()));
+      const close = keys.getKeys("tui.select.cancel").join("/") || "Esc";
+      if (width < 24 || height < 7)
+        return [`Profiles · ${close}: close`, "Resize for details"]
+          .slice(0, height)
+          .map((line) => truncateToWidth(line, width));
+      const inner = width - 4;
+      const wide = width >= 88;
+      const leftWidth = wide ? Math.min(28, Math.floor(inner / 3)) : inner;
+      const rightWidth = wide ? inner - leftWidth - 3 : inner;
+      const bodyHeight = height - 4;
+      const listHeight = wide ? bodyHeight : Math.min(3, Math.max(1, Math.floor(bodyHeight / 3)));
+      viewport = wide ? bodyHeight : Math.max(1, bodyHeight - listHeight - 1);
+      const start = Math.max(0, selected - listHeight + 1);
+      const roster = profiles
+        .slice(start, start + listHeight)
+        .map((profile, index) =>
+          theme.fg(
+            start + index === selected ? "accent" : "text",
+            `${start + index === selected ? ">" : " "} ${safe(profile.name).replaceAll("\n", " ")}`,
+          ),
+        );
+      const lines = (
+        profiles[selected] ? details(profiles[selected]) : ["No resolved profiles"]
+      ).flatMap((text) =>
+        safe(text)
+          .split("\n")
+          .flatMap((line) => wrapTextWithAnsi(line, rightWidth)),
+      );
+      maximum = Math.max(0, lines.length - viewport);
+      offset = Math.min(maximum, offset);
+      const detail = lines.slice(offset, offset + viewport);
+      const body = wide
+        ? Array.from(
+            { length: bodyHeight },
+            (_, index) =>
+              cell(roster[index] ?? "", leftWidth) +
+              theme.fg("border", " │ ") +
+              cell(detail[index] ?? "", rightWidth),
+          )
+        : [
+            ...roster,
+            ...Array(Math.max(0, listHeight - roster.length)).fill(""),
+            "─".repeat(inner),
+            ...detail,
+          ];
+      const row = (text: string) =>
+        theme.style(`│ ${cell(text, inner)} │`, { bg: theme.colors.customMessageBg });
+      return [
+        row(theme.fg("accent", "Subagent Profiles · resolved · read-only")),
+        ...body.map(row),
+        row(
+          `${selected + (profiles.length ? 1 : 0)}/${profiles.length} · detail ${offset + 1}–${Math.min(lines.length, offset + viewport)}/${lines.length}`,
+        ),
+        row("↑↓ select · j/k scroll · PgUp/Dn · Home/End"),
+        row(`${close}: close · callable tools unknown here`),
+      ].slice(0, height);
+    },
+    handleInput(data) {
+      if (keys.matches(data, "tui.select.cancel")) {
+        done();
+        return;
+      }
+      if (keys.matches(data, "tui.select.up") || keys.matches(data, "tui.select.down")) {
+        selected = Math.max(
+          0,
+          Math.min(profiles.length - 1, selected + (keys.matches(data, "tui.select.up") ? -1 : 1)),
+        );
+        offset = 0;
+      } else if (data === "j") offset = Math.min(maximum, offset + 1);
+      else if (data === "k") offset = Math.max(0, offset - 1);
+      else if (keys.matches(data, "tui.select.pageDown"))
+        offset = Math.min(maximum, offset + viewport);
+      else if (keys.matches(data, "tui.select.pageUp")) offset = Math.max(0, offset - viewport);
+      else if (matchesKey(data, "home")) offset = 0;
+      else if (matchesKey(data, "end")) offset = maximum;
+      else return;
+      requestRender();
+    },
+    invalidate() {},
+  };
+}

package/src/profiles.ts

@@ -0,0 +1,225 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import {
+  CONFIG_DIR_NAME,
+  getAgentDir,
+  loadSkills,
+  type Skill,
+} from "@earendil-works/pi-coding-agent";
+
+import { narrowModelPolicy, allowsModel, sameSelection, type ModelPolicy } from "./model-policy.ts";
+
+export const READ_TOOLS = ["read", "grep", "find", "ls"] as const;
+export const WRITE_TOOLS = [...READ_TOOLS, "write", "edit", "bash"] as const;
+export type BuiltinTool = (typeof WRITE_TOOLS)[number];
+export const COORDINATION_ACTIONS = ["message", "inbox", "wait"] as const;
+export type CoordinationAction = (typeof COORDINATION_ACTIONS)[number];
+/** Tool arrays are ceilings; admission intersects callable parent builtins before writer/ancestry checks. */
+export type Profile = Readonly<
+  ModelPolicy & {
+    name: string;
+    description: string;
+    prompt: string;
+    tools: readonly BuiltinTool[];
+    skills: readonly string[];
+    /** Operator-reviewed leaf tools; never a tool-to-tool forwarding grant. */
+    leafTools?: readonly string[];
+    spawn?: readonly string[];
+    coordination?: readonly CoordinationAction[];
+  }
+>;
+const bundled: Record<string, Profile> = {
+  general: {
+    name: "general",
+    description: "General delegation with restricted parent capabilities",
+    prompt: "Complete the assigned analysis and report the evidence and limitations.",
+    tools: WRITE_TOOLS,
+    skills: [],
+    spawn: ["scout", "review"],
+  },
+  scout: {
+    name: "scout",
+    description: "Explore and locate evidence",
+    prompt:
+      "Explore the assignment using read-only tools. Report precise source locations and findings.",
+    tools: READ_TOOLS,
+    skills: [],
+    spawn: ["scout", "review"],
+  },
+  review: {
+    name: "review",
+    description: "Review without modifying files",
+    prompt:
+      "Review the assigned work. Report actionable findings with source locations; do not edit files.",
+    tools: READ_TOOLS,
+    skills: [],
+    spawn: ["scout", "review"],
+  },
+  implementation: {
+    name: "implementation",
+    description:
+      "Implement changes in the supplied workspace (exclusive model-tool writer; manual shells are uncoordinated)",
+    prompt:
+      "Implement the assigned bounded change, verify it and report changed files and remaining risks. Work in your supplied cwd; root permissions and global model-tool writer coordination still apply.",
+    tools: WRITE_TOOLS,
+    skills: [],
+    spawn: ["scout", "review"],
+  },
+};
+
+async function config(path: string): Promise<Record<string, unknown>> {
+  try {
+    const value: unknown = JSON.parse(await readFile(path, "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value))
+      throw new Error("expected object");
+    return value as Record<string, unknown>;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw new Error(`Invalid delegation config ${path}: ${String(error)}`);
+  }
+}
+function strings(value: unknown, field: string): string[] {
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string"))
+    throw new Error(`${field} must be a string array`);
+  return value;
+}
+function specialize(base: Profile, value: unknown, operator: boolean): Profile {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`Invalid profile ${base.name}`);
+  const input = value as Record<string, unknown>;
+  for (const key of Object.keys(input))
+    if (
+      ![
+        "description",
+        "prompt",
+        "tools",
+        "skills",
+        "leafTools",
+        "spawn",
+        "coordination",
+        "models",
+        "model",
+        "prewalk",
+      ].includes(key)
+    )
+      throw new Error(`Unsupported profile field: ${key}`);
+  const tools = input.tools === undefined ? [...base.tools] : strings(input.tools, "tools");
+  if (tools.some((tool) => !base.tools.includes(tool as BuiltinTool)))
+    throw new Error(`Profile ${base.name} cannot broaden tool grants`);
+  const skills = input.skills === undefined ? [...base.skills] : strings(input.skills, "skills");
+  if (skills.some((path) => !isAbsolute(path) || (!operator && !base.skills.includes(path))))
+    throw new Error(
+      `Profile ${base.name} cannot mint skill grants; operator paths must be absolute`,
+    );
+  const leafTools =
+    input.leafTools === undefined
+      ? [...(base.leafTools ?? [])]
+      : strings(input.leafTools, "leafTools");
+  if (
+    leafTools.some(
+      (name) => !name || base.name !== "general" || (!operator && !base.leafTools?.includes(name)),
+    )
+  )
+    throw new Error("Cannot mint leaf tool grants");
+  for (const field of ["description", "prompt"] as const)
+    if (input[field] !== undefined && typeof input[field] !== "string")
+      throw new Error(`${field} must be text`);
+  const spawn = input.spawn === undefined ? [...(base.spawn ?? [])] : strings(input.spawn, "spawn");
+  if (
+    spawn.some(
+      (name) => !Object.hasOwn(bundled, name) || (!operator && !base.spawn?.includes(name)),
+    )
+  )
+    throw new Error("Cannot mint spawn grants");
+  const coordination =
+    input.coordination === undefined
+      ? [...(base.coordination ?? [])]
+      : strings(input.coordination, "coordination");
+  if (
+    coordination.some(
+      (action) =>
+        !COORDINATION_ACTIONS.includes(action as CoordinationAction) ||
+        (!operator && !base.coordination?.includes(action as CoordinationAction)),
+    )
+  )
+    throw new Error("Cannot mint coordination grants");
+  return {
+    ...base,
+    ...narrowModelPolicy(base, input, operator),
+    coordination: coordination as CoordinationAction[],
+    spawn,
+    description: (input.description as string) ?? base.description,
+    prompt: (input.prompt as string) ?? base.prompt,
+    tools: tools as BuiltinTool[],
+    skills,
+    leafTools,
+  };
+}
+
+/** Operator config can grant exact skill paths; trusted project config can only narrow those grants. */
+export async function resolveProfile(
+  name: string,
+  cwd: string,
+  trusted: boolean,
+  operatorDir = getAgentDir(),
+  availableSkills: readonly Skill[] = [],
+): Promise<{ profile: Profile; skills: Skill[] }> {
+  let profile = bundled[name];
+  if (!Object.hasOwn(bundled, name)) throw new Error(`Unknown delegation profile: ${name}`);
+  if (name === "general")
+    profile = { ...profile, skills: availableSkills.map((skill) => skill.filePath) };
+  const user = await config(join(operatorDir, "delegation.json"));
+  for (const key of Object.keys(user))
+    if (key !== "scheduling" && !Object.hasOwn(bundled, key))
+      throw new Error(`Unknown operator profile: ${key}`);
+  if (user[name] !== undefined) profile = specialize(profile, user[name], true);
+  if (trusted) {
+    const project = await config(join(cwd, CONFIG_DIR_NAME, "delegation.json"));
+    for (const key of Object.keys(project))
+      if (key !== "scheduling" && !Object.hasOwn(bundled, key))
+        throw new Error(`Unknown project profile: ${key}`);
+    if (project[name] !== undefined) profile = specialize(profile, project[name], false);
+  }
+  for (const path of profile.skills) await readFile(path, "utf8");
+  const loaded = loadSkills({
+    cwd,
+    agentDir: operatorDir,
+    skillPaths: [...profile.skills],
+    includeDefaults: false,
+  });
+  if (loaded.diagnostics.length || loaded.skills.length !== profile.skills.length)
+    throw new Error(
+      "Granted skills must be valid, distinct skill files (not discovery directories)",
+    );
+  return { profile, skills: loaded.skills };
+}
+export function isWriter(profile: Profile): boolean {
+  return (
+    !!profile.leafTools?.length ||
+    profile.tools.some((tool) => !READ_TOOLS.includes(tool as (typeof READ_TOOLS)[number]))
+  );
+}
+
+export function bundledProfiles(): Profile[] {
+  return structuredClone(Object.values(bundled));
+}
+
+/** Keep current definitions/prompts but intersect executable grants with an admitted ceiling. */
+export function intersectProfileGrants(profile: Profile, maximum: Profile): Profile {
+  return {
+    ...profile,
+    models:
+      maximum.models === undefined
+        ? undefined
+        : (profile.models ?? []).filter((selection) => allowsModel(maximum, selection)),
+    prewalk:
+      profile.prewalk && maximum.prewalk && sameSelection(profile.prewalk, maximum.prewalk)
+        ? profile.prewalk
+        : undefined,
+    tools: profile.tools.filter((tool) => maximum.tools.includes(tool)),
+    leafTools: profile.leafTools?.filter((name) => maximum.leafTools?.includes(name)),
+    skills: profile.skills.filter((skill) => maximum.skills.includes(skill)),
+    spawn: profile.spawn?.filter((role) => maximum.spawn?.includes(role)),
+    coordination: profile.coordination?.filter((action) => maximum.coordination?.includes(action)),
+  };
+}

package/src/scheduling.ts

@@ -0,0 +1,73 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export type ExecutionLimits = {
+  deadlineMs: number;
+  requests: number;
+  tools: number;
+  depth: number;
+  spawns: number;
+};
+export type SchedulingPolicy = ExecutionLimits & {
+  concurrency: number;
+  queue: number;
+  batch: number;
+};
+export const DEFAULT_POLICY: Readonly<SchedulingPolicy> = {
+  concurrency: 16,
+  queue: 32,
+  batch: 16,
+  depth: 2,
+  spawns: 8,
+  deadlineMs: 600000,
+  requests: 100,
+  tools: 100,
+};
+const ceilings: SchedulingPolicy = {
+  concurrency: 16,
+  queue: 256,
+  batch: 64,
+  depth: 4,
+  spawns: 32,
+  deadlineMs: 3600000,
+  requests: 1000,
+  tools: 1000,
+};
+export function narrowLimits<T extends object>(base: T, value: unknown, maximum: T = base): T {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Limits must be an object");
+  const result = { ...base };
+  for (const [key, number] of Object.entries(value)) {
+    if (
+      !Object.hasOwn(base, key) ||
+      !Number.isSafeInteger(number) ||
+      (number as number) < (key === "depth" || key === "spawns" || key === "queue" ? 0 : 1) ||
+      (number as number) > (maximum as Record<string, number>)[key]
+    )
+      throw new Error(`Invalid or broadened limit: ${key}`);
+    (result as Record<string, unknown>)[key] = number;
+  }
+  return result;
+}
+export function validatePolicy(value: unknown): SchedulingPolicy {
+  return narrowLimits({ ...DEFAULT_POLICY }, value, ceilings);
+}
+export async function resolveScheduling(
+  cwd: string,
+  trusted: boolean,
+  operatorDir = getAgentDir(),
+): Promise<SchedulingPolicy> {
+  async function load(path: string): Promise<unknown> {
+    try {
+      return JSON.parse(await readFile(path, "utf8")).scheduling ?? {};
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+      throw error;
+    }
+  }
+  const operator = validatePolicy(await load(join(operatorDir, "delegation.json")));
+  return trusted
+    ? narrowLimits(operator, await load(join(cwd, CONFIG_DIR_NAME, "delegation.json")))
+    : operator;
+}

package/src/task-input.ts

@@ -0,0 +1,73 @@
+import { stat, realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import type { ExtensionToolContext, ReadToolDetails } from "@earendil-works/pi-coding-agent";
+
+function hasDeniedTaskComponent(path: string): boolean {
+  return path.split(/[\\/]/).some((part) => part.startsWith(".") || part === "node_modules");
+}
+
+/** Content is obtained only through the effective public read dispatcher, never raw filesystem reads. */
+export async function readTaskInput(
+  path: string,
+  ctx: ExtensionToolContext,
+  signal?: AbortSignal,
+  beforeRead?: () => void,
+  cwd = ctx.cwd,
+): Promise<string> {
+  if (!path || isAbsolute(path) || path.includes("\0") || hasDeniedTaskComponent(path))
+    throw new Error(
+      "taskFile must be an explicit non-hidden workspace-relative path without traversal",
+    );
+  if (!ctx.tools.some((tool) => tool.name === "read"))
+    throw new Error("taskFile requires a callable parent read tool");
+  const base = await realpath(cwd);
+  const target = resolve(base, path);
+  const checkedPath = await realpath(target);
+  const inside = relative(base, checkedPath);
+  if (!inside || inside === ".." || inside.startsWith(".." + sep) || isAbsolute(inside))
+    throw new Error("taskFile escapes workspace");
+  if (hasDeniedTaskComponent(inside))
+    throw new Error("taskFile resolved target must be non-hidden and outside node_modules");
+  const before = await stat(target);
+  if (!before.isFile() || before.size === 0 || before.size > 50000)
+    throw new Error("taskFile must be a nonempty regular text file of at most 50000 bytes");
+  signal?.throwIfAborted();
+  beforeRead?.();
+  const outcome = await ctx.executeTool("read", { path: target }, { signal });
+  if (outcome.isError)
+    throw new Error(
+      "taskFile read denied or failed: " +
+        outcome.result.content
+          .filter((block) => block.type === "text")
+          .map((block) => block.text)
+          .join("\n"),
+    );
+  const details = outcome.result.details as ReadToolDetails | undefined;
+  if (
+    details?.truncation?.truncated ||
+    outcome.result.content.length !== 1 ||
+    outcome.result.content[0].type !== "text"
+  )
+    throw new Error("taskFile must be complete untruncated text");
+  const text = outcome.result.content[0].text;
+  if (
+    !text.trim() ||
+    text.includes("\0") ||
+    text.includes("\ufffd") ||
+    Buffer.byteLength(text) > 50000
+  )
+    throw new Error(
+      "taskFile must contain nonempty UTF-8 text without replacement characters or NUL",
+    );
+  const after = await stat(target);
+  if (
+    (await realpath(target)) !== checkedPath ||
+    before.dev !== after.dev ||
+    before.ino !== after.ino ||
+    before.size !== after.size ||
+    before.mtimeMs !== after.mtimeMs ||
+    before.ctimeMs !== after.ctimeMs
+  )
+    throw new Error("taskFile changed during preflight; retry");
+  return text;
+}