@tduyng/pi-subagent 0.0.0-stage → 0.0.1

package/src/subagent/helpers.ts

@@ -0,0 +1,212 @@
+import { execFile } from 'node:child_process'
+import { stat } from 'node:fs/promises'
+import { basename, dirname } from 'node:path'
+import { promisify } from 'node:util'
+
+import { DEFAULT_MAX_TURNS, MAX_CONCURRENT } from './types.js'
+
+export const MAX_DELAY_MS = 2_147_483_647
+
+export const MIN_TIMEOUT_MS = 30 * 60_000
+
+export async function abortableDelay(ms: number, signal: AbortSignal | undefined): Promise<void> {
+    if (signal?.aborted) throw new Error('Subagent aborted.')
+    ms = Math.min(ms, MAX_DELAY_MS)
+    await new Promise<void>((resolve, reject) => {
+        const cleanup = () => signal?.removeEventListener('abort', onAbort)
+        const timer = setTimeout(() => {
+            cleanup()
+            resolve()
+        }, ms)
+        const onAbort = () => {
+            clearTimeout(timer)
+            cleanup()
+            reject(new Error('Subagent aborted.'))
+        }
+        signal?.addEventListener('abort', onAbort, { once: true })
+    })
+}
+
+export function resolveTimeoutMs(ms: number | undefined): number | undefined {
+    return ms !== undefined && Number.isFinite(ms) && ms > 0 ? Math.max(ms, MIN_TIMEOUT_MS) : undefined
+}
+
+export function resolveMaxTurns(requested: number | undefined, profile: number | undefined): number {
+    const valid = (value: number | undefined): value is number =>
+        value !== undefined && Number.isFinite(value) && value >= 1
+    const fallback = valid(profile) ? profile : DEFAULT_MAX_TURNS
+    return Math.floor(valid(requested) ? requested : fallback)
+}
+
+export function wrapUpMessage(hasSchema: boolean): string {
+    const close = hasSchema
+        ? 'call `structured_output` now with what you already have'
+        : 'reply now with your final answer'
+    return `Turn budget spent: this is your last turn. Stop investigating and ${close}, naming what you could not finish.`
+}
+
+export function structuredRecoveryMessage(attempt: number): string {
+    const lead =
+        'You finished without calling the `structured_output` tool. Do not investigate further. Call `structured_output` now, exactly once, with the fields the task requires, using the findings you already have.'
+    return attempt <= 1 ? lead : `${lead} The parent cannot use a plain text answer for this task; this is reminder ${attempt}.`
+}
+
+export function isProviderSchemaError(error: Error | string): boolean {
+    const message = error instanceof Error ? error.message : error
+    return (
+        /tool[_ ]schema|schema.*invalid|invalid[_ ]schema|structured[_ ]output|json_schema|response[_ ]format|response_format/i.test(
+            message
+        ) || /invalid request parameters/i.test(message)
+    )
+}
+
+export function shouldRetryWithoutSchema(error: Error | string, hasSchema: boolean): boolean {
+    return hasSchema && isProviderSchemaError(error)
+}
+
+export interface RunOutcome {
+    hasAssistant: boolean
+    timedOut: boolean
+    duration: string | undefined
+    hitTurnLimit: boolean
+    maxTurns: number
+    aborted: boolean
+    hasSchema: boolean
+    hasStructured: boolean
+    output: string
+    stopReason: string | undefined
+    errorMessage: string | undefined
+}
+
+export function failureReason(outcome: RunOutcome): string | undefined {
+    if (outcome.timedOut) {
+        return `Timed out after ${outcome.duration ?? 'the deadline'}. Raise timeoutMs or narrow the task.`
+    }
+    if (outcome.aborted || (!outcome.hitTurnLimit && outcome.stopReason === 'aborted')) return 'Cancelled'
+    if (!outcome.hasAssistant) return 'Child produced no response.'
+    if (outcome.stopReason === 'error') return outcome.errorMessage ?? 'Child produced no response.'
+    if (outcome.hitTurnLimit && !outcome.output && !outcome.hasStructured) return 'Child produced no response.'
+    return undefined
+}
+
+export function salvageOutput(assistant: { content?: unknown } | undefined): string | undefined {
+    if (!assistant) return undefined
+    const content = assistant.content
+    if (!Array.isArray(content)) return undefined
+    const text = content
+        .filter((part): part is { type: 'text'; text: string } => {
+            if (!part) return false
+            const p = part as { type: unknown; text: unknown }
+            return p.type === 'text' && p.text != null
+        })
+        .map((part) => String(part.text))
+        .join('')
+        .trim()
+    return text || undefined
+}
+
+export function salvageFromMessages(messages: readonly unknown[] | undefined): string | undefined {
+    if (!messages) return undefined
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index] as { role?: unknown; content?: unknown } | undefined
+        if (!message || message.role !== 'assistant') continue
+        const text = salvageOutput(message)
+        if (text) return text
+    }
+    return undefined
+}
+
+export function childPromptExtras(
+    model: { baseUrl?: string } | undefined,
+    parentPrompt: string,
+    schemaInstruction: string | undefined
+): string[] {
+    const inherited = model?.baseUrl === 'claude-bridge' ? parentPrompt.trim() : ''
+    return [inherited, schemaInstruction].filter((part): part is string => Boolean(part))
+}
+
+export async function validateCwd(cwd: string): Promise<void> {
+    let info
+    try {
+        info = await stat(cwd)
+    } catch {
+        throw new Error(`Subagent working directory does not exist: ${cwd}`)
+    }
+    if (!info.isDirectory()) throw new Error(`Subagent working directory is not a directory: ${cwd}`)
+}
+
+const execFileAsync = promisify(execFile)
+
+export async function createWorktree(repo: string, target: string): Promise<void> {
+    try {
+        await execFileAsync('git', ['-C', repo, 'worktree', 'add', '-b', worktreeBranch(target), target, 'HEAD'])
+    } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error)
+        throw new Error(`Could not create a worktree under ${repo}: ${reason}`, { cause: error })
+    }
+}
+
+/** The branch a worktree at `target` commits to, named after the task directory holding it. */
+export function worktreeBranch(target: string): string {
+    return `pi-task-${basename(dirname(target))}`
+}
+
+export function gitStatus(repo: string): Promise<string> {
+    return execFileAsync('git', ['-C', repo, 'status', '--porcelain']).then(
+        (result) => result.stdout,
+        () => ''
+    )
+}
+
+export function changedPaths(status: string): string[] {
+    return status
+        .split('\n')
+        .filter((line) => line.trim())
+        .map((line) => {
+            const arrow = line.indexOf(' -> ')
+            const raw = arrow >= 0 ? line.slice(arrow + 4) : line.slice(3)
+            return raw.trim().replace(/^"|"$/g, '')
+        })
+}
+
+let permitsInUse = 0
+const permitWaiters: Array<() => void> = []
+
+export async function acquirePermit(signal: AbortSignal | undefined): Promise<void> {
+    if (signal?.aborted) throw new Error('Subagent aborted while queued.')
+    if (permitsInUse < MAX_CONCURRENT) {
+        permitsInUse++
+        return
+    }
+    await new Promise<void>((resolve, reject) => {
+        const waiter = () => {
+            signal?.removeEventListener('abort', onAbort)
+            permitsInUse++
+            resolve()
+        }
+        const onAbort = () => {
+            const index = permitWaiters.indexOf(waiter)
+            if (index >= 0) permitWaiters.splice(index, 1)
+            reject(new Error('Subagent aborted while queued.'))
+        }
+        permitWaiters.push(waiter)
+        signal?.addEventListener('abort', onAbort, { once: true })
+    })
+}
+
+export function releasePermit(): void {
+    permitsInUse--
+    permitWaiters.shift()?.()
+}
+
+export function findDuplicateTask(tasks: readonly string[]): { first: number; second: number } | undefined {
+    const seen = new Map<string, number>()
+    for (let index = 0; index < tasks.length; index++) {
+        const key = (tasks[index] ?? '').trim().replace(/\s+/g, ' ').toLowerCase()
+        if (!key) continue
+        const first = seen.get(key)
+        if (first !== undefined) return { first, second: index }
+        seen.set(key, index)
+    }
+    return undefined
+}