@justjoshn/pi-pstack 0.0.0-stage → 0.15.36-pi.1

package/src/subscriptions/webhook.ts

@@ -0,0 +1,209 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { join } from 'node:path';
+
+export const DEFAULT_ROUTINES_PORT = 47913;
+export const MAX_BODY_BYTES = 64 * 1024;
+const HOST = '127.0.0.1';
+const KEY = /^[0-9a-f]{64}$/;
+
+export function routineSlug(name: string): string {
+  const slug = name
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (slug === '') throw new Error(`Routine name "${name}" has no letters or digits to make a slug from.`);
+  return slug.slice(0, 64).replace(/-+$/, '');
+}
+
+export function credentialFile(routinesDir: string, slug: string): string {
+  return join(routinesDir, slug, 'credentials.json');
+}
+
+function readKey(file: string): string | undefined {
+  try {
+    const key = (JSON.parse(readFileSync(file, 'utf8')) as { key?: unknown } | null)?.key;
+    return typeof key === 'string' && KEY.test(key) ? key : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const errno = (error: unknown) => (typeof error === 'object' && error !== null && 'code' in error ? String((error as { code: unknown }).code) : undefined);
+const pause = (ms: number) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+/** The routine's sender key file, created with a fresh key unless a valid one is already there. Returns the path only. */
+export function ensureCredentials(routinesDir: string, slug: string): string {
+  const file = credentialFile(routinesDir, slug);
+  mkdirSync(join(routinesDir, slug), { recursive: true, mode: 0o700 });
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const key = readKey(file);
+    if (key !== undefined) {
+      chmodSync(file, 0o600);
+      return file;
+    }
+    if (!existsSync(file)) {
+      try {
+        writeFileSync(file, `${JSON.stringify({ key: randomBytes(32).toString('hex') })}\n`, { flag: 'wx', mode: 0o600 });
+        chmodSync(file, 0o600);
+        return file;
+      } catch (error) {
+        if (errno(error) !== 'EEXIST') throw error;
+      }
+    }
+    if (attempt < 4) pause(5);
+  }
+  if (readKey(file) !== undefined) {
+    chmodSync(file, 0o600);
+    return file;
+  }
+  writeFileSync(file, `${JSON.stringify({ key: randomBytes(32).toString('hex') })}\n`, { mode: 0o600 });
+  chmodSync(file, 0o600);
+  return file;
+}
+
+const digest = (text: string) => createHash('sha256').update(text).digest();
+
+/** Constant-time: both sides are hashed first, so length differences do not leak either. */
+export function keyMatches(presented: string | undefined, expected: string | undefined): boolean {
+  if (presented === undefined || expected === undefined) return false;
+  return timingSafeEqual(digest(presented), digest(expected));
+}
+
+function presentedKey(request: IncomingMessage): string | undefined {
+  const header = request.headers['x-automation-key'];
+  if (typeof header === 'string' && header !== '') return header.trim();
+  const bearer = /^Bearer\s+(\S+)\s*$/i.exec(request.headers.authorization ?? '');
+  return bearer?.[1];
+}
+
+export interface WebhookEvent {
+  headers: Record<string, string>;
+  bodyDigest: string;
+  body: string;
+  timestampMs: number;
+}
+
+/** JSON whose `<` is escaped, so a body cannot close the surrounding tag; it still parses to the same value. */
+const tagSafeJson = (value: unknown) => JSON.stringify(value, null, 2).replace(/</g, '\\u003c');
+
+export function webhookEventBlock(event: WebhookEvent): string {
+  return ['<webhook_event>', tagSafeJson({ headers: event.headers, body_digest: event.bodyDigest, body: event.body, timestamp_ms: event.timestampMs }), '</webhook_event>'].join('\n');
+}
+
+export interface RoutineRoute {
+  slug: string;
+  credentialFile: string;
+  onEvent: (event: WebhookEvent) => void;
+}
+
+const reply = (response: ServerResponse, status: number, message: string) => {
+  response.writeHead(status, { 'content-type': 'application/json', connection: 'close' });
+  response.end(`${JSON.stringify(status === 200 ? { ok: true } : { error: message })}\n`);
+};
+
+/** One local listener for every routine of this process. Routes are looked up per request, so they can change while it runs. */
+export class RoutineServer {
+  private server: Server | undefined;
+  private listening: Promise<number> | undefined;
+  readonly routes = new Map<string, RoutineRoute>();
+  private readonly port: number;
+
+  constructor(port: number) {
+    this.port = port;
+  }
+
+  /** Starts the listener once and resolves to its port. */
+  start(): Promise<number> {
+    this.listening ??= new Promise<number>((resolve, reject) => {
+      const server = createServer((request, response) => this.handle(request, response));
+      server.once('error', (error: NodeJS.ErrnoException) => {
+        this.listening = undefined;
+        this.server = undefined;
+        reject(new Error(error.code === 'EADDRINUSE' ? `Port ${this.port} on ${HOST} is in use (another Pi process may own the routines listener). Set PSTACK_ROUTINES_PORT to a free port.` : `Routines listener failed: ${error.message}`));
+      });
+      server.listen(this.port, HOST, () => {
+        server.unref();
+        resolve((server.address() as AddressInfo).port);
+      });
+      this.server = server;
+    });
+    return this.listening;
+  }
+
+  async url(slug: string): Promise<string> {
+    return `http://${HOST}:${await this.start()}/routines/${slug}`;
+  }
+
+  isListening(): boolean {
+    return this.server?.listening === true;
+  }
+
+  close(): void {
+    this.server?.close();
+    this.server?.closeAllConnections();
+    this.server = undefined;
+    this.listening = undefined;
+  }
+
+  private handle(request: IncomingMessage, response: ServerResponse): void {
+    const slug = /^\/routines\/([a-z0-9-]+)\/?$/.exec(new URL(request.url ?? '/', 'http://localhost').pathname)?.[1];
+    const route = slug === undefined ? undefined : this.routes.get(slug);
+    if (route === undefined) {
+      reply(response, 404, 'No such routine.');
+      return;
+    }
+    if (request.method !== 'POST') {
+      response.setHeader('allow', 'POST');
+      reply(response, 405, 'Use POST.');
+      return;
+    }
+    if (!keyMatches(presentedKey(request), readKey(route.credentialFile))) {
+      reply(response, 401, 'Wrong or missing sender key.');
+      return;
+    }
+    if (Number(request.headers['content-length'] ?? 0) > MAX_BODY_BYTES) {
+      reply(response, 413, `Body over ${MAX_BODY_BYTES} bytes.`);
+      return;
+    }
+    const chunks: Buffer[] = [];
+    let size = 0;
+    let done = false;
+    request.on('data', (chunk: Buffer) => {
+      if (done) return;
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        done = true;
+        reply(response, 413, `Body over ${MAX_BODY_BYTES} bytes.`);
+        request.resume();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    request.on('end', () => {
+      if (done) return;
+      done = true;
+      const raw = Buffer.concat(chunks);
+      const body = raw.toString('utf8');
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(body);
+      } catch {
+        parsed = undefined;
+      }
+      if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return reply(response, 400, 'Body must be a JSON object.');
+      const headers: Record<string, string> = {};
+      for (const name of ['content-type', 'user-agent'] as const) {
+        const header = request.headers[name];
+        if (typeof header === 'string') headers[name] = header;
+      }
+      route.onEvent({ headers, bodyDigest: createHash('sha256').update(raw).digest('hex'), body, timestampMs: Date.now() });
+      reply(response, 200, 'ok');
+    });
+  }
+}

package/src/task/agents.ts

@@ -0,0 +1,55 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+import { parseFrontmatter } from '@earendil-works/pi-coding-agent';
+import { AGENTS_DIR } from '../paths.ts';
+
+/** A subagent type from an agent file: name, description, model, readonly, is_background, prompt body. */
+export interface AgentDefinition {
+  type: string;
+  description: string;
+  model?: string;
+  readonly: boolean;
+  background: boolean;
+  prompt: string;
+  file?: string;
+}
+
+export const GENERAL_PURPOSE: AgentDefinition = {
+  type: 'generalPurpose',
+  description: 'General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. Use when a search or task needs several steps of its own.',
+  readonly: false,
+  background: false,
+  prompt: '',
+};
+
+function parseAgentFile(file: string): AgentDefinition {
+  const { frontmatter, body } = parseFrontmatter(readFileSync(file, 'utf8'));
+  const name = frontmatter['name'];
+  const description = frontmatter['description'];
+  const model = frontmatter['model'];
+  return {
+    type: typeof name === 'string' && name.trim() !== '' ? name.trim() : basename(file, '.md'),
+    description: typeof description === 'string' ? description.trim() : '',
+    ...(typeof model === 'string' && model.trim() !== '' ? { model: model.trim() } : {}),
+    readonly: frontmatter['readonly'] === true,
+    background: frontmatter['is_background'] === true,
+    prompt: body.trim(),
+    file,
+  };
+}
+
+/** generalPurpose first, then every `*.md` agent file in `dir` sorted by file name. */
+export function loadAgentDefinitions(dir: string = AGENTS_DIR): AgentDefinition[] {
+  const files = readdirSync(dir)
+    .filter((name) => name.endsWith('.md'))
+    .toSorted();
+  return [GENERAL_PURPOSE, ...files.map((name) => parseAgentFile(join(dir, name)))];
+}
+
+export function findAgent(agents: readonly AgentDefinition[], type: string | undefined): AgentDefinition {
+  const wanted = type ?? GENERAL_PURPOSE.type;
+  const agent = agents.find((candidate) => candidate.type === wanted);
+  if (agent) return agent;
+  throw new Error(`Unknown subagent_type "${wanted}". Available subagent types: ${agents.map((candidate) => candidate.type).join(', ')}.`);
+}

package/src/task/card.ts

@@ -0,0 +1,32 @@
+import type { AgentToolResult } from '@earendil-works/pi-agent-core';
+import { Text } from '@earendil-works/pi-tui';
+
+const COLLAPSED_LINES = 10;
+
+interface CardDetails {
+  subagentType: string;
+  model: { provider: string; id: string; thinking?: string } | null;
+  worktree?: { branch: string } | null;
+  description?: string;
+}
+
+function isCardDetails(details: unknown): details is CardDetails {
+  return typeof details === 'object' && details !== null && 'subagentType' in details && 'model' in details;
+}
+
+/** Heads the Task result with the Task description and the model that ran. */
+export function taskCardText(result: Pick<AgentToolResult<unknown>, 'content' | 'details'>, expanded: boolean): string {
+  const text = result.content.map((part) => (part.type === 'text' ? part.text : '')).join('\n');
+  const lines = text.split('\n');
+  const body = expanded || lines.length <= COLLAPSED_LINES ? lines : [...lines.slice(0, COLLAPSED_LINES), `… ${lines.length - COLLAPSED_LINES} more lines`];
+  if (!isCardDetails(result.details)) return body.join('\n');
+  const { model, subagentType, worktree, description } = result.details;
+  const modelName = model === null ? "Pi's default model" : `${model.provider}/${model.id}${model.thinking === undefined ? '' : `:${model.thinking}`}`;
+  const branch = worktree === undefined || worktree === null ? '' : ` · branch ${worktree.branch}`;
+  const title = description === undefined || description.trim() === '' ? '' : `${description.trim()} · `;
+  return [`${title}${subagentType} · ${modelName}${branch}`, ...body].join('\n');
+}
+
+export function renderTaskCard(result: AgentToolResult<unknown>, options: { expanded: boolean }): Text {
+  return new Text(taskCardText(result, options.expanded), 0, 0);
+}

package/src/task/format.ts

@@ -0,0 +1,88 @@
+// Model-facing texts: a <response> block, an "Agent ID:" line that names `resume`, and a <task> notification block
+// with the same fields.
+import type { Usage } from '@earendil-works/pi-ai';
+import { DEFAULT_MAX_BYTES, formatSize, truncateHead } from '@earendil-works/pi-coding-agent';
+import type { Worktree } from './worktree.ts';
+
+/** The first `limit` bytes, cut back to a UTF-8 character boundary (past 10xxxxxx continuation bytes). */
+function headBytes(bytes: Buffer, limit: number): string {
+  let end = limit;
+  while (end > 0 && ((bytes[end] ?? 0) & 0xc0) === 0x80) end -= 1;
+  return bytes.subarray(0, end).toString('utf8');
+}
+
+/**
+ * Bounds a response with Pi's own tool-output limits (truncateHead: 2000 lines or 50KB). truncateHead keeps whole
+ * lines and returns nothing when the first line alone is too long, and a subagent's reply can be one long line, so
+ * that case keeps the line's first 50KB instead.
+ */
+export function bounded(text: string, transcript: string | undefined): string {
+  const result = truncateHead(text);
+  if (!result.truncated) return text;
+  const where = `the full response is in ${transcript ?? 'the subagent transcript'}`;
+  if (result.firstLineExceedsLimit) {
+    const head = headBytes(Buffer.from(text, 'utf8'), DEFAULT_MAX_BYTES);
+    return `${head}\n[truncated: showing ${formatSize(Buffer.byteLength(head, 'utf8'))} of ${formatSize(result.totalBytes)}; ${where}]`;
+  }
+  const size = result.truncatedBy === 'bytes' ? ` (${formatSize(result.outputBytes)} of ${formatSize(result.totalBytes)})` : '';
+  return `${result.content}\n[truncated: showing ${result.outputLines} of ${result.totalLines} lines${size}; ${where}]`;
+}
+
+const agentIdLine = (agentId: string) => `Agent ID: ${agentId} (pass it as \`resume\` to send a follow-up after it completes)`;
+const transcriptLine = (transcript: string | undefined) => (transcript === undefined ? [] : [`Transcript: ${transcript}`]);
+
+export function foregroundText(agentId: string, response: string, transcript: string | undefined, notes: readonly string[] = []): string {
+  return ['This is the output of the subagent:', '', 'response:', '<response>', bounded(response, transcript), '</response>', '', agentIdLine(agentId), ...transcriptLine(transcript), ...notes].join('\n');
+}
+
+export function backgroundText(agentId: string, transcript: string | undefined, notes: readonly string[] = []): string {
+  return [
+    'Subagent is running in the background. Its final response arrives automatically after your turn ends, so do not wait or poll for it. End your turn or work on something else.',
+    '',
+    agentIdLine(agentId),
+    ...transcriptLine(transcript),
+    ...notes,
+  ].join('\n');
+}
+
+export function steerText(agentId: string, notes: readonly string[] = []): string {
+  return [
+    `Sent to agent ${agentId} while it runs: it reads the message after its current step. Its final response still arrives as its launch said, as a completion notification for a background agent or as the waiting Task result for a foreground one, so do not wait or poll for it.`,
+    ...notes,
+  ].join('\n');
+}
+
+export function worktreeLine(worktree: Worktree): string {
+  return `Worktree: ${worktree.path} on branch ${worktree.branch}, from ${worktree.base} at ${worktree.commit}. Merge ${worktree.branch} to take the subagent's commits.`;
+}
+
+/** Opens a cloud agent's first prompt, since nothing else tells the child that the parent merges from its branch. */
+export function worktreePreface(worktree: Worktree, prompt: string): string {
+  const where = worktree.cwd === worktree.path ? worktree.path : `${worktree.path} (working directory ${worktree.cwd})`;
+  return `You are running in an isolated git worktree at ${where} on branch ${worktree.branch}, created from ${worktree.base} at ${worktree.commit}. Uncommitted changes in the parent's checkout are not here. Commit your changes to ${worktree.branch} before you finish, because the parent agent merges from that branch.\n\n${prompt}`;
+}
+
+export interface NotificationFields {
+  status: 'success' | 'error';
+  agentId: string;
+  title: string;
+  toolCallId: string;
+  detail: string;
+  /** What the background child spent. It stays in the notification details, because Pi gives extensions no way to add it to session totals. */
+  usage?: Usage;
+}
+
+export function notificationText(fields: NotificationFields): string {
+  return [
+    'The following task has finished. If you already handled it, ignore this notification and do not restate earlier responses.',
+    '',
+    '<task>',
+    'kind: subagent',
+    `status: ${fields.status}`,
+    `task_id: ${fields.agentId}`,
+    `title: ${fields.title}`,
+    `tool_call_id: ${fields.toolCallId}`,
+    `detail: ${fields.detail}`,
+    '</task>',
+  ].join('\n');
+}

package/src/task/models.ts

@@ -0,0 +1,140 @@
+export type Effort = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+
+export interface AvailableModel {
+  provider: string;
+  id: string;
+  reasoning: boolean;
+  /** Thinking levels Pi supports for the model (pi-ai `getSupportedThinkingLevels`). */
+  levels: readonly string[];
+}
+
+/** A concrete child model. `thinking` absent means the child's own default for that model. */
+export interface ModelSpec {
+  provider: string;
+  id: string;
+  thinking?: Effort;
+}
+
+const INHERIT = new Set(['', 'inherit', 'inherit-parent', 'auto', 'default']);
+const EFFORTS = new Set<string>(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+const DASH_SLUG = /^(.+?)(?:-thinking)?(?:-(none|minimal|low|medium|high|xhigh|max))?(-fast)?$/;
+
+const asEffort = (value: string): Effort | undefined => (EFFORTS.has(value) ? (value as Effort) : undefined);
+
+/** A model as the allowed list names it, with its thinking levels when it has more than off. */
+export function modelLabel(model: AvailableModel): string {
+  const levels = model.levels.filter((level) => level !== 'off').length > 0 ? ` (thinking: ${model.levels.join(', ')})` : '';
+  return `${model.provider}/${model.id}${levels}`;
+}
+
+function invalid(value: string, available: readonly AvailableModel[], reason = 'Model could not be resolved to a valid subagent model.'): Error {
+  return new Error(
+    [
+      `Invalid model selection "${value}". ${reason}`,
+      'Allowed model slugs:',
+      '- inherit',
+      ...available.map((model) => `- ${modelLabel(model)}`),
+      '',
+      'Add a thinking level as <model>:<level>, for example claude-opus-5-5:xhigh, or as <model>[effort=<level>].',
+      'The `model` parameter is optional. If omitted, the subagent uses the same model as the parent agent.',
+    ].join('\n'),
+  );
+}
+
+type Find = (reference: string) => AvailableModel | undefined;
+
+/** A bare id that several providers offer means the parent chat's provider when it is one of them. */
+function findModel(reference: string, available: readonly AvailableModel[], parentProvider: string | undefined): AvailableModel | undefined {
+  const slash = reference.indexOf('/');
+  if (slash !== -1) return available.find((model) => model.provider === reference.slice(0, slash) && model.id === reference.slice(slash + 1));
+  const matches = available.filter((model) => model.id === reference);
+  if (matches.length > 1) return matches.find((model) => model.provider === parentProvider) ?? failAmbiguous(reference, matches);
+  return matches[0];
+}
+
+function failAmbiguous(reference: string, matches: readonly AvailableModel[]): never {
+  throw new Error(`Model "${reference}" matches more than one provider: ${matches.map((model) => `${model.provider}/${model.id}`).join(', ')}. Use <provider>/<model-id>.`);
+}
+
+/** Only listed levels are accepted, so a level the model does not support is refused instead of clamped by Pi. */
+class UnsupportedLevel extends Error {}
+
+function withThinking(model: AvailableModel, thinking: Effort | undefined): ModelSpec {
+  if (thinking === undefined) return { provider: model.provider, id: model.id };
+  if (!model.levels.includes(thinking)) throw new UnsupportedLevel(`${model.provider}/${model.id} does not support thinking level ${thinking}; it supports ${model.levels.join(', ')}.`);
+  return { provider: model.provider, id: model.id, thinking };
+}
+
+/** A whole reference first, since model ids such as llama3:8b contain a colon; then a trailing :<effort>. */
+function resolvePiSpec(value: string, find: Find): ModelSpec | undefined {
+  const whole = find(value);
+  if (whole !== undefined) return withThinking(whole, undefined);
+  const colon = value.lastIndexOf(':');
+  const level = colon === -1 ? undefined : asEffort(value.slice(colon + 1));
+  if (level === undefined) return undefined;
+  const model = find(value.slice(0, colon));
+  return model === undefined ? undefined : withThinking(model, level);
+}
+
+/** Legacy `<id>[-<effort>][-fast]` slugs: a Pi model whose own id ends in -fast wins, else the base id; the effort is the thinking level, and `none` is Pi's `off`. */
+function resolveDashSlug(value: string, find: Find): ModelSpec | undefined {
+  const match = DASH_SLUG.exec(value);
+  const base = match?.[1];
+  const effort = match?.[2] === undefined ? undefined : asEffort(match[2] === 'none' ? 'off' : match[2]);
+  const fast = match?.[3] !== undefined;
+  if (base === undefined || (effort === undefined && !fast)) return undefined;
+  const model = (fast ? find(`${base}-fast`) : undefined) ?? find(base);
+  return model === undefined ? undefined : withThinking(model, effort);
+}
+
+interface ModelParameters {
+  effort?: Effort;
+  fast?: boolean;
+}
+
+const BRACKETED = /^(.+)\[([^\]]*)\]$/;
+
+/** `id=value` pairs. Pi sets a context window per model, not per call, so `context` is accepted and has no effect. */
+function parseModelParameters(text: string): ModelParameters | undefined {
+  let parsed: ModelParameters = {};
+  for (const pair of text
+    .split(',')
+    .map((part) => part.trim())
+    .filter((part) => part !== '')) {
+    const [key, value, ...rest] = pair.split('=').map((part) => part.trim());
+    if (value === undefined || value === '' || rest.length > 0) return undefined;
+    const effort = asEffort(value);
+    if (key === 'effort' && effort !== undefined) parsed = { ...parsed, effort };
+    else if (key === 'fast' && (value === 'true' || value === 'false')) parsed = { ...parsed, fast: value === 'true' };
+    else if (key !== 'context') return undefined;
+  }
+  return parsed;
+}
+
+/** `<model>[effort=high,fast=false,context=300k]`, per-model parameters; `[]` is the standard variant. */
+function resolveBracketed(value: string, find: Find): ModelSpec | undefined {
+  const match = BRACKETED.exec(value);
+  const base = match?.[1];
+  const parameters = parseModelParameters(match?.[2] ?? '');
+  if (base === undefined || parameters === undefined) return undefined;
+  const model = (parameters.fast === true ? find(`${base}-fast`) : undefined) ?? find(base);
+  return model === undefined ? undefined : withThinking(model, parameters.effort);
+}
+
+/**
+ * Resolves Task's `model`: aliases run on the parent, a listed model runs as asked, and anything else fails with the
+ * allowed list. Legacy slugs `<id>-<effort>[-fast]` still map to a Pi model plus thinking level.
+ */
+export function resolveSubagentModel(value: string | undefined, available: readonly AvailableModel[], parent: ModelSpec | undefined): ModelSpec | undefined {
+  const requested = (value ?? '').trim();
+  if (INHERIT.has(requested)) return parent;
+  try {
+    const find: Find = (reference) => findModel(reference, available, parent?.provider);
+    const resolved = resolveBracketed(requested, find) ?? resolvePiSpec(requested, find) ?? resolveDashSlug(requested, find);
+    if (resolved === undefined) throw invalid(requested, available);
+    return resolved;
+  } catch (error) {
+    if (error instanceof UnsupportedLevel) throw invalid(requested, available, error.message);
+    throw error;
+  }
+}