@tduyng/pi-subagent 0.0.0-stage → 0.0.1

package/src/subagent/durable.ts

@@ -0,0 +1,264 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import * as path from 'node:path'
+
+import { getAgentDir, type SessionManager } from '@earendil-works/pi-coding-agent'
+import { Validator, type Infer } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+
+import type { JsonPayload } from './structured.js'
+import { RUNS_DIR, type TaskDetails, type ThinkingLevel } from './types.js'
+
+const RUN_FILE = 'run.json'
+const OWNER_FILE = 'owner.json'
+export const MAX_CHECKPOINT_OUTPUT = 64 * 1024
+export const CONTINUE_PROMPT =
+    'Continue your previous task from where you stopped. Finish the work and reply with your final answer, naming anything you could not finish.'
+
+const JsonValueSchema = t.any()
+
+const DurableTaskSchema = t.object({
+    id: t.string(),
+    index: t.number(),
+    label: t.string(),
+    task: t.string(),
+    cwd: t.string(),
+    provider: t.string(),
+    model: t.string(),
+    thinking: t.string(),
+    maxTurns: t.number(),
+    timeoutMs: t.optional(t.number()),
+    isolation: t.optional(t.literal('worktree')),
+    forkContext: t.boolean(),
+    sessionDir: t.string(),
+    agent: t.optional(t.string()),
+    schema: t.optional(JsonValueSchema),
+    worktree: t.optional(t.string()),
+    sessionFile: t.optional(t.string()),
+    status: t.union([
+        t.literal('queued'),
+        t.literal('running'),
+        t.literal('completed'),
+        t.literal('failed')
+    ]),
+    output: t.optional(t.string()),
+    error: t.optional(t.string()),
+    partial: t.optional(t.boolean()),
+    structured: t.optional(JsonValueSchema),
+    turnCount: t.optional(t.number()),
+    toolCallCount: t.optional(t.number()),
+    usage: t.optional(
+        t.object({ input: t.number(), output: t.number(), cost: t.number() })
+    ),
+    touched: t.optional(t.array(t.string())),
+    changes: t.optional(t.array(t.string())),
+    startedAt: t.optional(t.number()),
+    finishedAt: t.optional(t.number())
+})
+
+const OwnerSchema = t.object({ pid: t.number(), at: t.number() })
+const RecoveryDetailsSchema = t.object({ runId: t.string() })
+const isRecoveryDetailsSchema = new Validator(RecoveryDetailsSchema).isValidObject
+
+const DurableRunSchema = t.object({
+    version: t.literal(1),
+    runId: t.string(),
+    sessionId: t.string(),
+    toolCallId: t.optional(t.string()),
+    startedAt: t.number(),
+    finishedAt: t.optional(t.number()),
+    tasks: t.array(DurableTaskSchema)
+})
+
+type Mutable<T> = { -readonly [K in keyof T]: T[K] }
+export type DurableTask = Mutable<Omit<Infer<typeof DurableTaskSchema>, 'thinking' | 'schema' | 'structured'>> & {
+    thinking: ThinkingLevel
+    schema?: JsonPayload
+    structured?: JsonPayload
+}
+export type DurableRun = Mutable<Omit<Infer<typeof DurableRunSchema>, 'tasks'>> & { tasks: DurableTask[] }
+const isDurableRunSchema = new Validator(DurableRunSchema).isValidObject
+const isOwnerSchema = new Validator(OwnerSchema).isValidObject
+
+function isDurableRun(value: unknown): value is DurableRun {
+    return isDurableRunSchema(value)
+}
+
+export function runDirectory(sessionId: string, runId: string): string {
+    return path.join(getAgentDir(), RUNS_DIR, sessionId, runId)
+}
+
+export function saveRun(run: DurableRun): void {
+    try {
+        const directory = runDirectory(run.sessionId, run.runId)
+        mkdirSync(directory, { recursive: true, mode: 0o700 })
+        const target = path.join(directory, RUN_FILE)
+        const temporary = `${target}.tmp`
+        writeFileSync(temporary, JSON.stringify(boundedRun(run)), { mode: 0o600 })
+        renameSync(temporary, target)
+    } catch {}
+}
+
+function boundedRun(run: DurableRun): DurableRun {
+    return {
+        ...run,
+        tasks: run.tasks.map((task) =>
+            task.output && task.output.length > MAX_CHECKPOINT_OUTPUT
+                ? { ...task, output: `${task.output.slice(0, MAX_CHECKPOINT_OUTPUT)}\n[checkpoint truncated]` }
+                : task
+        )
+    }
+}
+
+export function readRun(file: string): DurableRun | undefined {
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'))
+        return isDurableRun(parsed) ? parsed : undefined
+    } catch {
+        return undefined
+    }
+}
+
+export function runUpdatedAt(sessionId: string, runId: string): number | undefined {
+    try {
+        return statSync(path.join(runDirectory(sessionId, runId), RUN_FILE)).mtimeMs
+    } catch {
+        return undefined
+    }
+}
+
+export function listRuns(sessionId: string): DurableRun[] {
+    const root = path.join(getAgentDir(), RUNS_DIR, sessionId)
+    let entries: string[]
+    try {
+        entries = readdirSync(root)
+    } catch {
+        return []
+    }
+    const runs: DurableRun[] = []
+    for (const entry of entries) {
+        const run = readRun(path.join(root, entry, RUN_FILE))
+        if (run) runs.push(run)
+    }
+    return runs.toSorted((a, b) => a.startedAt - b.startedAt)
+}
+
+export function findRunForTask(sessionId: string, taskId: string): DurableRun | undefined {
+    return listRuns(sessionId).find((run) => run.tasks.some((task) => task.id === taskId))
+}
+
+export function detailsFromRecord(record: DurableTask): TaskDetails {
+    return {
+        id: record.id,
+        index: record.index,
+        label: record.label,
+        agent: record.agent,
+        status: record.status,
+        cwd: record.cwd,
+        provider: record.provider,
+        model: record.model,
+        thinking: record.thinking,
+        activity: undefined,
+        turnCount: record.turnCount,
+        toolCallCount: record.toolCallCount,
+        touched: record.touched,
+        usage: record.usage,
+        output: record.output,
+        partial: record.partial,
+        hasSchema: record.schema !== undefined,
+        maxTurns: record.maxTurns,
+        structured: record.structured,
+        error: record.error,
+        sessionFile: record.sessionFile,
+        worktree: record.worktree,
+        changes: record.changes,
+        forkContext: record.forkContext,
+        startedAt: record.startedAt,
+        finishedAt: record.finishedAt
+    }
+}
+
+export function syncRecord(record: DurableTask, task: TaskDetails): void {
+    record.status = task.status
+    record.output = task.output
+    record.error = task.error
+    record.partial = task.partial
+    record.structured = task.structured
+    record.turnCount = task.turnCount
+    record.toolCallCount = task.toolCallCount
+    record.usage = task.usage
+    record.touched = task.touched
+    record.changes = task.changes
+    record.sessionFile = task.sessionFile ?? record.sessionFile
+    record.worktree = task.worktree ?? record.worktree
+    record.startedAt = task.startedAt ?? record.startedAt
+    record.finishedAt = task.finishedAt ?? record.finishedAt
+}
+
+export function pendingTasks(run: DurableRun): DurableTask[] {
+    return run.tasks.filter((task) => task.status === 'queued' || task.status === 'running')
+}
+
+export function resolveSessionFile(record: DurableTask): string | undefined {
+    if (record.sessionFile && existsSync(record.sessionFile)) return record.sessionFile
+    try {
+        const newest = readdirSync(record.sessionDir)
+            .map((file) => ({ file: path.join(record.sessionDir, file), stat: statSync(path.join(record.sessionDir, file)) }))
+            .filter((entry) => entry.file.endsWith('.jsonl') && entry.stat.size > 0)
+            .map((entry) => ({ file: entry.file, at: entry.stat.mtimeMs }))
+            .toSorted((a, b) => b.at - a.at)[0]
+        return newest?.file
+    } catch {
+        return undefined
+    }
+}
+
+export function deliveredKeys(manager: Pick<SessionManager, 'getEntries'>): Set<string> {
+    const keys = new Set<string>()
+    for (const entry of manager.getEntries()) {
+        if (entry.type === 'custom_message' && entry.customType === 'subagent-durable') {
+            if (isRecoveryDetailsSchema(entry.details)) keys.add(entry.details.runId)
+            continue
+        }
+        if (entry.type !== 'message') continue
+        const message = entry.message as { role?: string; toolCallId?: string }
+        if (message.role === 'toolResult' && message.toolCallId) keys.add(message.toolCallId)
+    }
+    return keys
+}
+
+function pidAlive(pid: number): boolean {
+    try {
+        process.kill(pid, 0)
+        return true
+    } catch (error) {
+        return (error as NodeJS.ErrnoException).code === 'EPERM'
+    }
+}
+
+function ownerPid(file: string): number | undefined {
+    try {
+        const owner = JSON.parse(readFileSync(file, 'utf8'))
+        return isOwnerSchema(owner) ? owner.pid : undefined
+    } catch {
+        return undefined
+    }
+}
+
+export function claimRun(sessionId: string, runId: string): boolean {
+    const ownerFile = path.join(runDirectory(sessionId, runId), OWNER_FILE)
+    const pid = ownerPid(ownerFile)
+    if (pid !== undefined && pid !== process.pid && pidAlive(pid)) return false
+    try {
+        writeFileSync(ownerFile, JSON.stringify({ pid: process.pid, at: Date.now() }), { mode: 0o600 })
+        return true
+    } catch {
+        return false
+    }
+}
+
+export function releaseClaim(sessionId: string, runId: string): void {
+    try {
+        rmSync(path.join(runDirectory(sessionId, runId), OWNER_FILE), { force: true })
+    } catch {}
+}

package/src/subagent/format.ts

@@ -0,0 +1,241 @@
+import * as path from 'node:path'
+
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import type { AssistantMessage, JsonValue, UserMessage } from '@earendil-works/pi-ai'
+import { Validator } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+
+import { type RunDetails, type RunStatus, type TaskDetails, type ToolCallArguments } from './types.js'
+const isString = new Validator(t.string()).isValidObject
+
+export function formatDuration(startedAt: number | undefined, finishedAt = Date.now()): string | undefined {
+    if (startedAt === undefined) return undefined
+    const seconds = Math.max(0, Math.round((finishedAt - startedAt) / 1000))
+    if (seconds < 60) return `${seconds}s`
+    return `${Math.floor(seconds / 60)}m ${seconds % 60}s`
+}
+
+export function statusIcon(status: RunStatus, theme: Theme): string {
+    if (status === 'completed') return theme.fg('success', '✓')
+    if (status === 'failed') return theme.fg('error', '✗')
+    return theme.fg('warning', status === 'queued' ? '◦' : '●')
+}
+
+export function taskHeadline(task: TaskDetails): string {
+    const bits = [
+        task.status,
+        formatDuration(task.startedAt, task.finishedAt),
+        `${task.provider}/${task.model} (${task.thinking})`
+    ]
+    if (task.status === 'running' && task.activity) bits.push(task.activity)
+    if (task.turnCount !== undefined && task.turnCount > 0) bits.push(`${task.turnCount} turns`)
+    const name = `${task.label}${task.agent ? ` · ${task.agent}` : ''}`
+    return `${name}: ${bits.filter(Boolean).join(' · ')}`
+}
+
+export function fmtTokens(count: number): string {
+    return count < 1000 ? String(count) : `${(count / 1000).toFixed(1)}k`
+}
+
+export function usageLine(task: TaskDetails): string | undefined {
+    if (!task.usage) return undefined
+    const { input, output, cost } = task.usage
+    const costText = cost > 0 ? ` ($${cost.toFixed(4)})` : ''
+    return `   tokens: ${fmtTokens(input)} in / ${fmtTokens(output)} out${costText}`
+}
+
+function shortenPath(p: string): string {
+    const home = process.env['HOME'] ?? ''
+    return home && p.startsWith(home) ? `~${p.slice(home.length)}` : p
+}
+
+export function truncate(text: string, max: number): string {
+    return text.length > max ? `${text.slice(0, max)}…` : text
+}
+
+export function touchedPath(toolName: string, args: ToolCallArguments | undefined, cwd: string): string | undefined {
+    if (!args || (toolName !== 'read' && toolName !== 'write' && toolName !== 'edit')) return undefined
+    const raw = args.path ?? args.file_path
+    if (!raw) return undefined
+    const absolute = path.resolve(cwd, raw)
+    const relative = path.relative(cwd, absolute)
+    return relative && !relative.startsWith('..') ? relative : shortenPath(absolute)
+}
+
+export function describeActivity(toolName: string, args: ToolCallArguments | undefined): string {
+    if (!args) return toolName
+    switch (toolName) {
+        case 'bash': {
+            const cmd = String(args.command ?? '')
+                .replace(/\s+/g, ' ')
+                .trim()
+            return `$ ${truncate(cmd, 50)}`
+        }
+        case 'read': {
+            const p = shortenPath(String(args.path ?? args.file_path ?? ''))
+            return `read ${p}`
+        }
+        case 'write': {
+            const p = shortenPath(String(args.path ?? args.file_path ?? ''))
+            const lines = args.content ? String(args.content).split('\n').length : 0
+            return lines > 1 ? `write ${p} (${lines} lines)` : `write ${p}`
+        }
+        case 'edit': {
+            const p = shortenPath(String(args.path ?? args.file_path ?? ''))
+            return `edit ${p}`
+        }
+        case 'grep': {
+            const pat = String(args.pattern ?? '')
+            const p = shortenPath(String(args.path ?? '.'))
+            return `grep /${truncate(pat, 30)}/ in ${p}`
+        }
+        case 'find': {
+            const pat = String(args.pattern ?? '*')
+            const p = shortenPath(String(args.path ?? '.'))
+            return `find ${truncate(pat, 30)} in ${p}`
+        }
+        case 'ls': {
+            const p = shortenPath(String(args.path ?? '.'))
+            return `ls ${p}`
+        }
+        default: {
+            const raw = args.command ?? args.path ?? args.url ?? args.query
+            if (!raw) return toolName
+            const text = String(raw).replace(/\s+/g, ' ').trim()
+            return `${toolName}(${truncate(text, 40)})`
+        }
+    }
+}
+
+export function countByStatus(tasks: TaskDetails[]): string {
+    const counts = new Map<RunStatus, number>()
+    for (const task of tasks) counts.set(task.status, (counts.get(task.status) ?? 0) + 1)
+    return [...counts].map(([status, count]) => `${count} ${status}`).join(', ')
+}
+
+export function partialText(details: RunDetails): string {
+    const lines = [`Subagent run: ${countByStatus(details.tasks)}.`]
+    for (const task of details.tasks) lines.push('', taskHeadline(task))
+    return lines.join('\n')
+}
+
+export function resultText(details: RunDetails): string {
+    const duration = formatDuration(details.startedAt, details.finishedAt)
+    const lines = [
+        `Subagent run${duration ? ` finished after ${duration}` : ''}: ${countByStatus(details.tasks)}.`,
+        'Each child ran in-process in this same pi session.'
+    ]
+    for (const task of details.tasks) {
+        lines.push('', `── ${taskHeadline(task)}`)
+        if (task.sessionFile) lines.push(`   session: ${task.sessionFile}`)
+        if (task.worktree) {
+            lines.push(`   worktree: ${task.worktree}`)
+            if (task.changes?.length) {
+                const listed = task.changes.slice(0, 10).join(', ')
+                lines.push(`   changed (${task.changes.length}): ${listed}${task.changes.length > 10 ? ', …' : ''}`)
+            } else lines.push('   no changes in the worktree')
+        }
+        const usage = usageLine(task)
+        if (usage) lines.push(usage)
+        if (task.toolCallCount !== undefined && task.toolCallCount > 0) lines.push(`   tools: ${task.toolCallCount}`)
+        if (task.touched?.length) lines.push(`   read/wrote: ${task.touched.join(', ')}`)
+        if (task.error) lines.push(`   error: ${task.error}`)
+        if (task.partial) lines.push('   [partial answer — resume to finish]')
+        if (task.status === 'failed') lines.push(`   resume: ${task.id}`)
+        if (task.structured !== undefined) lines.push(`   structured: ${JSON.stringify(task.structured)}`)
+        if (task.output) lines.push('', task.output)
+    }
+    return lines.join('\n')
+}
+
+export function extractUserText(message: UserMessage): string {
+    const content = message.content
+    if (!Array.isArray(content)) return content
+    return content
+        .filter((part): part is Extract<typeof part, { type: 'text' }> => part.type === 'text')
+        .map((part) => part.text)
+        .join('\n')
+}
+
+const TextPartSchema = t.object({ type: t.literal('text'), text: t.string() }, { additionalProperties: true })
+const isTextPartSchema = new Validator(TextPartSchema).isValidObject
+
+export function extractForkText(content: JsonValue | undefined): string | undefined {
+    if (isString(content)) return content.trim() || undefined
+    if (Array.isArray(content)) {
+        return (
+            content
+                .flatMap((part) => (isTextPartSchema(part) ? [part.text] : []))
+                .join('\n')
+                .trim() || undefined
+        )
+    }
+    return undefined
+}
+
+export function summarizeToolCall(name: string, args: ToolCallArguments): string {
+    return describeActivity(name, args)
+}
+
+export function buildTranscriptLines(messages: readonly unknown[], theme: Theme): string[] {
+    const lines: string[] = []
+    for (const message of messages) {
+        const role = (message as { role?: string }).role
+        if (role === 'user') {
+            const text = extractUserText(message as UserMessage)
+            if (text) lines.push('', theme.fg('accent', `› ${text}`))
+        } else if (role === 'assistant') {
+            for (const part of (message as AssistantMessage).content) {
+                if (part.type === 'thinking') {
+                    lines.push(theme.fg('dim', `· ${part.thinking.replace(/\s+/g, ' ').trim()}`))
+                } else if (part.type === 'text' && part.text.trim()) {
+                    lines.push(...part.text.split('\n'))
+                } else if (part.type === 'toolCall') {
+                    lines.push(theme.fg('toolTitle', `▸ ${summarizeToolCall(part.name, part.arguments)}`))
+                }
+            }
+        } else if (role === 'toolResult') {
+            const result = message as { content: Array<{ type: string; text: string }>; isError?: boolean }
+            const text = result.content
+                .filter((part): part is { type: 'text'; text: string } => part.type === 'text')
+                .map((part) => part.text)
+                .join('\n')
+            const preview = text.split('\n').slice(0, 5).join('\n')
+            if (preview)
+                lines.push(
+                    ...preview.split('\n').map((l) => theme.fg(result.isError ? 'error' : 'toolOutput', `  ${l}`))
+                )
+        } else {
+            const label = (message as { customType?: string }).customType
+            if (label) lines.push('', theme.fg('muted', `— ${label} —`))
+        }
+    }
+    return lines
+}
+
+export function toLabel(value: string, index: number): string {
+    const cleaned = value
+        .split('\n', 1)[0]
+        ?.trim()
+        .replace(/[^\w. -]/g, '')
+        .trim()
+        .slice(0, 24)
+    return cleaned ? `${index + 1}-${cleaned.replace(/\s+/g, '-')}` : `task-${index + 1}`
+}
+
+export function textFromAssistant(message: AssistantMessage): string {
+    return message.content
+        .filter((part): part is Extract<AssistantMessage['content'][number], { type: 'text' }> => part.type === 'text')
+        .map((part) => part.text)
+        .join('\n')
+}
+
+export function findLastAssistant(messages: readonly unknown[]): AssistantMessage | undefined {
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index] as { role?: string } | undefined
+        if (message?.role !== 'assistant') continue
+        return message as AssistantMessage
+    }
+    return undefined
+}