@orgloop/agentctl 1.0.1 → 1.2.0

package/dist/adapters/pi.d.ts

@@ -0,0 +1,96 @@
+import type { AgentAdapter, AgentSession, LaunchOpts, LifecycleEvent, ListOpts, PeekOpts, StopOpts } from "../core/types.js";
+export interface PidInfo {
+    pid: number;
+    cwd: string;
+    args: string;
+    /** Process start time from `ps -p <pid> -o lstart=`, used to detect PID recycling */
+    startTime?: string;
+}
+/** Metadata persisted by launch() so status checks survive wrapper exit */
+export interface LaunchedSessionMeta {
+    sessionId: string;
+    pid: number;
+    /** Process start time from `ps -p <pid> -o lstart=` for PID recycling detection */
+    startTime?: string;
+    /** The PID of the wrapper (agentctl launch) — may differ from `pid` (pi process) */
+    wrapperPid?: number;
+    cwd: string;
+    model?: string;
+    prompt?: string;
+    launchedAt: string;
+}
+export interface PiAdapterOpts {
+    piDir?: string;
+    sessionsMetaDir?: string;
+    getPids?: () => Promise<Map<number, PidInfo>>;
+    /** Override PID liveness check for testing (default: process.kill(pid, 0)) */
+    isProcessAlive?: (pid: number) => boolean;
+}
+/**
+ * Pi adapter — reads session data from ~/.pi/agent/sessions/
+ * and cross-references with running PIDs. NEVER maintains its own registry.
+ *
+ * Pi stores sessions as JSONL files in ~/.pi/agent/sessions/<cwd-slug>/<timestamp>_<id>.jsonl
+ * Each file starts with a type:'session' header line containing metadata.
+ */
+export declare class PiAdapter implements AgentAdapter {
+    readonly id = "pi";
+    private readonly piDir;
+    private readonly sessionsDir;
+    private readonly sessionsMetaDir;
+    private readonly getPids;
+    private readonly isProcessAlive;
+    constructor(opts?: PiAdapterOpts);
+    list(opts?: ListOpts): Promise<AgentSession[]>;
+    peek(sessionId: string, opts?: PeekOpts): Promise<string>;
+    /** Extract assistant messages from a JSONL session file */
+    private peekFromJsonl;
+    /** Get the log file path for a pending session from metadata */
+    private getLogPathForSession;
+    status(sessionId: string): Promise<AgentSession>;
+    launch(opts: LaunchOpts): Promise<AgentSession>;
+    /**
+     * Poll the launch log file for up to `timeoutMs` to extract the real session ID.
+     * Pi's JSONL output includes a session header with type: "session" and id field.
+     */
+    private pollForSessionId;
+    /**
+     * Fallback: poll the Pi sessions directory for a new JSONL file
+     * created after the launch time, matching the cwd.
+     */
+    private pollSessionDir;
+    stop(sessionId: string, opts?: StopOpts): Promise<void>;
+    resume(sessionId: string, message: string): Promise<void>;
+    events(): AsyncIterable<LifecycleEvent>;
+    /**
+     * Scan ~/.pi/agent/sessions/ recursively for .jsonl files and parse headers.
+     * Pi stores sessions at <sessionsDir>/<cwd-slug>/<timestamp>_<id>.jsonl
+     */
+    private discoverSessions;
+    /** Extract session ID from filename format: <timestamp>_<id>.jsonl */
+    private extractSessionIdFromFilename;
+    /** Parse the session header (type:'session') from the first few lines of a JSONL file */
+    private parseSessionHeader;
+    private buildSession;
+    private isSessionRunning;
+    /**
+     * Check whether a process plausibly belongs to a session by verifying
+     * the process started at or after the session's creation time.
+     * When start time is unavailable, defaults to false (assume no match).
+     */
+    private processStartedAfterSession;
+    private findMatchingPid;
+    /** Parse session tail for model, tokens, and cost aggregation */
+    private parseSessionTail;
+    /** Get the first user prompt from a session JSONL file */
+    private getFirstPrompt;
+    /** Find a session by exact or prefix ID match */
+    private findSession;
+    private findPidForSession;
+    /** Write session metadata to disk so status checks survive wrapper exit */
+    writeSessionMeta(meta: Omit<LaunchedSessionMeta, "startTime">): Promise<void>;
+    /** Read persisted session metadata */
+    readSessionMeta(sessionId: string): Promise<LaunchedSessionMeta | null>;
+    /** Delete stale session metadata */
+    private deleteSessionMeta;
+}