pi-t3-pstack 0.0.0-stage → 0.1.0

package/src/brief.ts

@@ -0,0 +1,280 @@
+import { Type } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Value } from "typebox/value";
+
+// The delegation brief (skills/poteto-mode/brief.md). The parent's guard
+// checks it before dispatch, and the child's extension reads its own limits
+// from it, so both sides parse it here.
+
+export type Size = "S" | "M" | "L";
+
+export interface Brief {
+  readonly acceptance: string | undefined;
+  readonly diskMb: number | undefined;
+  readonly files: readonly string[];
+  readonly job: string | undefined;
+  readonly minutes: number | undefined;
+  readonly sections: ReadonlyMap<string, string>;
+  readonly size: Size | undefined;
+}
+
+export interface BriefRules {
+  readonly jobs: readonly string[];
+  readonly noWrites: readonly string[];
+  readonly sizes: Readonly<
+    Record<string, { readonly files: number; readonly minutes: number }>
+  >;
+}
+
+export const SECTIONS = [
+  "Goal",
+  "Acceptance command",
+  "Files you may write",
+  "Non-goals",
+  "Context",
+  "Stop conditions",
+  "Report",
+] as const;
+
+const TASK_HEADING = /^# Task:/mu;
+
+// The user's approval of reasoning above high, as a whole message or line.
+export const APPROVAL_LINE = /^\s*allow (?:xhigh|max)\b/imu;
+
+// A /pstack- command where one can start: at the start of a line, or after a
+// space, quote or bracket. Inside a path such as artifacts/pstack-model-live.mjs
+// the slash follows a name, so it is not a command.
+export const PSTACK_COMMAND = /(?<![\w.~/-])\/pstack-/u;
+
+const BROAD_PATHS = new Set(["*", "**", "**/*", "/", ".", "./", "~"]);
+
+const number = (pattern: RegExp, text: string): number | undefined => {
+  const match = pattern.exec(text)?.groups?.value;
+
+  return match === undefined ? undefined : Number(match);
+};
+
+const listItems = (section: string | undefined): string[] =>
+  (section ?? "")
+    .split("\n")
+    .flatMap((line) => {
+      const item = /^\s*[-*]\s+(?<item>.+)$/u.exec(line)?.groups?.item;
+
+      if (item === undefined) {
+        return [];
+      }
+
+      const [first = ""] = item.replaceAll("`", "").trim().split(/\s+/u);
+
+      return [first.replace(/[:,]$/u, "")];
+    })
+    .filter((item) => item !== "");
+
+export const parseBrief = (text: string): Brief | undefined => {
+  const start = TASK_HEADING.exec(text);
+
+  if (start === null) {
+    return undefined;
+  }
+
+  const body = text.slice(start.index);
+  const header = body.split(/^## /mu)[0] ?? "";
+  const sections = new Map<string, string>();
+
+  for (const part of body.split(/^## /mu).slice(1)) {
+    const [title = "", ...rest] = part.split("\n");
+
+    sections.set(title.trim(), rest.join("\n"));
+  }
+
+  const fence = /```[^\n]*\n(?<code>[\s\S]*?)```/u.exec(
+    sections.get("Acceptance command") ?? ""
+  );
+
+  const size = /\bSize:\s*(?<size>[SML])\b/u.exec(header)?.groups?.size;
+
+  return {
+    acceptance: fence?.groups?.code?.trim() || undefined,
+    diskMb: number(/Disk limit:\s*(?<value>[\d.]+)\s*MB/iu, header),
+    files: listItems(sections.get("Files you may write")),
+    job: /\bJob:\s*(?<job>[a-z]+)/iu.exec(header)?.groups?.job?.toLowerCase(),
+    minutes: number(/Time limit:\s*(?<value>[\d.]+)\s*min/iu, header),
+    sections,
+    size: size === "S" || size === "M" || size === "L" ? size : undefined,
+  };
+};
+
+const textProblems = (text: string): string[] => {
+  const problems: string[] = [];
+
+  if (APPROVAL_LINE.test(text)) {
+    problems.push(
+      'A brief cannot carry the user\'s approval line ("allow xhigh"). Only the user grants it, in this chat.'
+    );
+  }
+
+  if (PSTACK_COMMAND.test(text)) {
+    problems.push(
+      "A brief cannot contain /pstack- commands. Account state is shared, so the child already sees it."
+    );
+  }
+
+  return problems;
+};
+
+const headerProblems = (brief: Brief, rules: BriefRules): string[] => {
+  const problems: string[] = [];
+
+  if (brief.job === undefined || !rules.jobs.includes(brief.job)) {
+    problems.push(
+      `The header needs "Job: <${rules.jobs.join(" | ")}>", the job type pstack_model routed.`
+    );
+  }
+
+  if (brief.size === undefined) {
+    problems.push('The header needs "Size: S" or "Size: M".');
+  } else if (brief.size === "L") {
+    problems.push(
+      "Size L is too large to delegate: split it into S or M tasks, or do it yourself."
+    );
+  }
+
+  if (brief.minutes === undefined || brief.minutes <= 0) {
+    problems.push('The header needs "Time limit: <N> min".');
+  }
+
+  if (brief.diskMb === undefined || brief.diskMb <= 0) {
+    problems.push('The header needs "Disk limit: <N> MB".');
+  }
+
+  return problems;
+};
+
+const sizeProblems = (brief: Brief, rules: BriefRules): string[] => {
+  const problems: string[] = [];
+  const limits = brief.size === undefined ? undefined : rules.sizes[brief.size];
+
+  if (
+    limits !== undefined &&
+    brief.minutes !== undefined &&
+    brief.minutes > limits.minutes
+  ) {
+    problems.push(
+      `Size ${brief.size} allows at most ${limits.minutes} min. Raise the size or split the task.`
+    );
+  }
+
+  if (limits !== undefined && brief.files.length > limits.files) {
+    problems.push(
+      `Size ${brief.size} allows at most ${limits.files} files in "Files you may write".`
+    );
+  }
+
+  return problems;
+};
+
+const sectionProblems = (brief: Brief): string[] => {
+  const problems: string[] = [];
+
+  for (const section of SECTIONS) {
+    if (!brief.sections.has(section)) {
+      problems.push(`Missing section "## ${section}".`);
+    }
+  }
+
+  if (
+    brief.sections.has("Acceptance command") &&
+    brief.acceptance === undefined
+  ) {
+    problems.push(
+      "The acceptance command must be a fenced code block under ## Acceptance command."
+    );
+  }
+
+  return problems;
+};
+
+const fileProblems = (brief: Brief, rules: BriefRules): string[] => {
+  const problems: string[] = [];
+
+  const readOnly =
+    brief.job !== undefined &&
+    rules.noWrites.includes(brief.job) &&
+    brief.files.length === 1 &&
+    brief.files[0]?.toLowerCase() === "none";
+
+  if (brief.sections.has("Files you may write") && brief.files.length === 0) {
+    problems.push(
+      '"Files you may write" needs at least one path (or "- none" for a review or check job).'
+    );
+  }
+
+  if (!readOnly) {
+    for (const file of brief.files) {
+      if (BROAD_PATHS.has(file) || file.toLowerCase() === "none") {
+        problems.push(
+          `"${file}" in "Files you may write" is not a narrow path. List the files or a narrow glob.`
+        );
+      }
+    }
+  }
+
+  return problems;
+};
+
+// Everything wrong with a brief, as one line each, so the parent can fix all
+// of it in one go.
+export const briefProblems = (text: string, rules: BriefRules): string[] => {
+  const problems = textProblems(text);
+  const brief = parseBrief(text);
+
+  if (brief === undefined) {
+    problems.push(
+      "The brief does not follow skills/poteto-mode/brief.md: it has no `# Task:` heading. Write it from that template."
+    );
+
+    return problems;
+  }
+
+  return [
+    ...problems,
+    ...headerProblems(brief, rules),
+    ...sizeProblems(brief, rules),
+    ...sectionProblems(brief),
+    ...fileProblems(brief, rules),
+  ];
+};
+
+// The parent's guard dispatches only briefs with this header and every
+// section, so a user's own prompt that opens with "# Task:" is not a child.
+const dispatchable = (brief: Brief): boolean =>
+  brief.job !== undefined &&
+  brief.size !== undefined &&
+  brief.minutes !== undefined &&
+  brief.diskMb !== undefined &&
+  SECTIONS.every((section) => brief.sections.has(section));
+
+// The brief that started this session, when it is a delegated child.
+export const sessionBrief = (
+  ctx: ExtensionContext
+): { readonly brief: Brief; readonly startedAt: number } | undefined => {
+  const first = ctx.sessionManager
+    .getBranch()
+    .find((entry) => entry.type === "message" && entry.message.role === "user");
+
+  if (first?.type !== "message" || first.message.role !== "user") {
+    return undefined;
+  }
+
+  const { content } = first.message;
+
+  const text = Value.Check(Type.String(), content)
+    ? content
+    : content.map((part) => (part.type === "text" ? part.text : "")).join("\n");
+
+  const brief = parseBrief(text);
+
+  return brief === undefined || !dispatchable(brief)
+    ? undefined
+    : { brief, startedAt: Date.parse(first.timestamp) };
+};

package/src/cards.ts

@@ -0,0 +1,65 @@
+import type { ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+
+const HTML_RENDER_TOOL = "mcp__t3-code__html_render";
+
+const MIN_FRAME_HEIGHT = 80;
+const MAX_FRAME_HEIGHT = 2000;
+
+export const escapeHtml = (text: string): string =>
+  text
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+
+const STYLE = `
+body{margin:0;font-family:var(--font-sans);color:var(--foreground);font-size:0.875rem;line-height:1.5}
+.card{background:var(--card);border:1px solid var(--border);border-radius:var(--radius);padding:16px}
+.head{display:flex;justify-content:space-between;align-items:baseline;gap:12px;margin-bottom:10px}
+.head h1{font-weight:600;font-size:inherit;margin:0}.muted{color:var(--muted-foreground)}
+.head h1,.note,.text{min-width:0;overflow-wrap:break-word}
+.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}
+ol{list-style:none;margin:0;padding:0}li{display:flex;gap:10px;padding:4px 0}
+.dot{width:16px;flex:none;text-align:center;color:var(--muted-foreground)}
+.completed .dot{color:var(--success)}.completed .text{color:var(--muted-foreground);text-decoration:line-through}
+.in_progress .dot{color:var(--info)}.in_progress .text{font-weight:600}
+.note{margin:0 0 10px;color:var(--muted-foreground)}
+pre{margin:0;white-space:pre-wrap;overflow-wrap:anywhere;font-family:var(--font-mono);font-size:0.875rem;background:var(--code-background);color:var(--code-foreground);border-radius:var(--radius);padding:12px}
+`;
+
+export const wrappedLines = (text: string, charsPerLine: number): number =>
+  text
+    .split("\n")
+    .reduce(
+      (lines, segment) =>
+        lines + Math.max(1, Math.ceil(segment.length / charsPerLine)),
+      0
+    );
+
+export const pageHtml = (title: string, body: string): string =>
+  `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escapeHtml(title)}</title><style>${STYLE}</style></head><body>${body}</body></html>`;
+
+export const frameHeight = (estimate: number): number =>
+  Math.min(MAX_FRAME_HEIGHT, Math.max(MIN_FRAME_HEIGHT, Math.ceil(estimate)));
+
+interface InlineCard {
+  readonly height: number;
+  readonly html: string;
+  readonly title: string;
+}
+
+export const renderInlineCard = async (
+  ctx: ExtensionToolContext,
+  card: InlineCard
+): Promise<boolean> => {
+  const available = ctx.tools.some((tool) => tool.name === HTML_RENDER_TOOL);
+
+  if (!available) {
+    return false;
+  }
+
+  const outcome = await ctx.executeTool(HTML_RENDER_TOOL, card);
+
+  return !outcome.isError;
+};