@phux/opencode 0.2.1

package/README.md

@@ -0,0 +1,35 @@
+# @phux/opencode
+
+OpenCode V2 plugin for operating shared terminals through an external local
+phux server and appending cache-preserving fleet context. Installation,
+configuration, tool behavior, target precedence,
+lifecycle gaps, and safety boundaries live in the canonical
+[OpenCode integration guide](../../docs/consumers/opencode.md).
+
+## Package development
+
+Install locked dependencies and run the deterministic, no-LLM gates from this
+directory:
+
+```sh
+npm ci
+npm run gates
+npm run smoke:opencode
+```
+
+`smoke:opencode` starts an isolated OpenCode V2 server and verifies that its
+resolved config accepts the built plugin URL. Plugin setup, registration,
+cleanup, and tool behavior are covered by `npm run gates`. The smoke requires
+an `opencode2` executable; set `OPENCODE_BIN` to choose it.
+
+The real packed-plugin smoke is opt-in and requires `phux >= 0.1.0`:
+
+```sh
+PHUX_OPENCODE_REAL_SMOKE=1 npm run smoke:real
+```
+
+It packs and installs the artifact in a temporary consumer, starts a private
+phux server on a temporary socket, invokes public create/run/snapshot tool
+definitions without an LLM, prints safe human attach argv, and tears down the
+server on normal exit, `SIGINT`, or `SIGTERM`. It never uses the default phux
+socket.

package/dist/index.d.ts

@@ -0,0 +1,535 @@
+import { Plugin } from '@opencode-ai/plugin';
+
+interface RunRequest {
+    readonly executable: string;
+    readonly args: readonly string[];
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly maxStdoutBytes?: number;
+    readonly maxStderrBytes?: number;
+}
+type OutputLimitStream = "stdout" | "stderr";
+interface ProcessResultBase {
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+type ProcessResult = (ProcessResultBase & {
+    readonly termination: "completed" | "aborted" | "timed_out";
+    readonly outputLimit?: never;
+}) | (ProcessResultBase & {
+    readonly termination: "output_limit";
+    readonly outputLimit: OutputLimitStream;
+});
+type ProcessRunner = (request: RunRequest) => Promise<ProcessResult>;
+
+interface SessionSummary {
+    readonly name: string;
+    readonly windows: number;
+    readonly attached: boolean;
+}
+interface SessionList {
+    readonly schema_version: 1 | 2;
+    readonly sessions: readonly SessionSummary[];
+    /** Canonical selectors for every addressable terminal (v2; empty for v1). */
+    readonly terminals: readonly string[];
+}
+interface CursorState {
+    readonly x: number;
+    readonly y: number;
+    readonly visible: boolean;
+}
+type CellColor = {
+    readonly kind: "default";
+} | {
+    readonly kind: "palette";
+    readonly index: number;
+} | {
+    readonly kind: "rgb";
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+};
+interface CellStyle {
+    readonly bold: boolean;
+    readonly faint: boolean;
+    readonly italic: boolean;
+    readonly underline: boolean;
+    readonly blink: boolean;
+    readonly inverse: boolean;
+    readonly invisible: boolean;
+    readonly strikethrough: boolean;
+    readonly overline: boolean;
+    readonly fg: CellColor;
+    readonly bg: CellColor;
+}
+interface CellInfo {
+    readonly col: number;
+    readonly row: number;
+    readonly semantic?: "output" | "input" | "prompt";
+    readonly style: CellStyle;
+}
+interface ScreenState {
+    readonly schema_version: 1 | 2 | 3;
+    readonly pane: number;
+    readonly cols: number;
+    readonly rows: number;
+    readonly cursor: CursorState | null;
+    readonly lines: readonly string[];
+    readonly scrollback: readonly string[];
+    readonly cells?: readonly CellInfo[];
+}
+interface RunResult {
+    readonly command: string;
+    readonly exit_code: number;
+    readonly output: string;
+    readonly duration_ms: number;
+    readonly truncated: boolean;
+}
+interface CreateResult {
+    readonly session: string;
+    readonly terminal_id: number;
+}
+interface SpawnResult {
+    readonly terminal_id: number;
+    readonly satellite: string | null;
+}
+interface LaunchResult {
+    readonly schema_version: 1;
+    readonly terminal_id: number;
+    readonly integration: string;
+    readonly plugin: string;
+    /** Validated because it is part of the CLI response, but never rendered to the model. */
+    readonly argv: readonly string[];
+}
+type SpatialDirection = "horizontal" | "vertical";
+interface InsertPaneResult {
+    readonly schema_version: 1;
+    readonly operation: "insert-pane";
+    readonly session_id: number;
+    readonly target_terminal_id: number;
+    readonly new_terminal_id: number;
+    readonly direction: SpatialDirection;
+    readonly ratio: number;
+}
+interface MovePaneResult {
+    readonly schema_version: 1;
+    readonly operation: "move-pane";
+    readonly session_id: number;
+    readonly source_terminal_id: number;
+    readonly target_terminal_id: number;
+    readonly direction: SpatialDirection;
+    readonly ratio: number;
+}
+interface SwapPaneResult {
+    readonly schema_version: 1;
+    readonly operation: "swap-pane";
+    readonly session_id: number;
+    readonly first_terminal_id: number;
+    readonly second_terminal_id: number;
+}
+interface AskedEvent {
+    readonly event: "asked";
+    readonly terminal: string;
+    readonly id: string;
+    readonly question: string;
+    readonly suggestions: readonly string[];
+    readonly elapsed_seconds: number | null;
+}
+type WatchEvent = {
+    readonly event: "title_changed";
+    readonly terminal?: string;
+    readonly title: string;
+} | {
+    readonly event: "command_started" | "bell" | "pane_spawned" | "dirty" | "idle";
+    readonly terminal?: string;
+} | {
+    readonly event: "command_finished";
+    readonly terminal?: string;
+    readonly exit_code: number | null;
+} | {
+    readonly event: "pane_closed";
+    readonly terminal?: string;
+    readonly exit_status: number | null;
+} | ({
+    readonly event: "asked";
+    readonly terminal?: string;
+} & Omit<AskedEvent, "event" | "terminal">) | {
+    readonly event: "unknown";
+    readonly terminal?: string;
+    readonly tag: number;
+};
+interface RenderedCell {
+    readonly grapheme: string;
+    readonly style: CellStyle;
+}
+interface RenderedFrame {
+    readonly schema_version: 1;
+    readonly cols: number;
+    readonly rows: number;
+    readonly cursor: CursorState | null;
+    readonly cells: readonly RenderedCell[];
+}
+interface TagRow {
+    readonly terminal: string;
+    /** Opaque human confirmation text; the current CLI has no tag JSON shape. */
+    readonly tagsText: string;
+}
+type AgentKind = "codex" | "claude" | "plugin" | "declared" | "unknown";
+type AgentState = "unknown" | "idle" | "working" | "blocked" | "done";
+type AgentAttention = "none" | "low" | "normal" | "high";
+interface AgentIdentity {
+    readonly id: string;
+    readonly label: string;
+    readonly kind: AgentKind;
+}
+interface AgentSource {
+    readonly kind: string;
+    readonly signal: string;
+    readonly confidence: number;
+    readonly observed: string;
+}
+interface AgentPane {
+    /** Canonical phux pane selector, for example @3 or host/@3. */
+    readonly terminal: string;
+    readonly session: string;
+    readonly window: string;
+    readonly agent: AgentIdentity;
+    readonly state: AgentState;
+    readonly confidence: number;
+    readonly attention: AgentAttention;
+    readonly title: string | null;
+    readonly cwd: string | null;
+    readonly sources: readonly AgentSource[];
+    readonly explanation: string;
+}
+interface AgentStateList {
+    readonly schema_version: 1;
+    readonly agents: readonly AgentPane[];
+}
+/**
+ * The declared `phux.agent/v1` record written by `phux agent set`.
+ *
+ * `state` and `attention` are OPTIONAL, per `docs/spec/L3.md` §3.7 where only
+ * `name` is required. Declaring a `state` outranks the server's derivation for
+ * the record's whole lifetime (ADR-0046 point 8), so an integration that can
+ * let the server derive should omit it and write identity alone.
+ */
+interface AgentRecord {
+    readonly name: string;
+    readonly kind: string;
+    readonly state?: AgentState;
+    readonly attention?: AgentAttention;
+    readonly session: string;
+}
+
+interface PhuxCliOptions {
+    readonly executable?: string;
+    readonly socket?: string;
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly runner?: ProcessRunner;
+    readonly maxStdoutBytes?: number;
+    readonly maxStderrBytes?: number;
+}
+interface ExecutionOptions {
+    /** Abort this local subprocess invocation. */
+    readonly signal?: AbortSignal;
+    /** Kill this local subprocess if it has not exited within this many ms. */
+    readonly timeoutMs?: number;
+}
+interface SnapshotOptions extends ExecutionOptions {
+    readonly target?: string;
+    /** true or zero means all retained history; a positive number bounds it. */
+    readonly scrollback?: boolean | number;
+    readonly cells?: boolean;
+}
+interface WaitOptions extends ExecutionOptions {
+    readonly target?: string;
+    readonly until?: string;
+    readonly idleMs?: number;
+    /** phux's own wait deadline, in seconds (distinct from local timeoutMs). */
+    readonly phuxTimeoutSeconds?: number;
+}
+type WaitOutcome = {
+    readonly outcome: "satisfied";
+    readonly screen: ScreenState;
+} | {
+    readonly outcome: "timed_out";
+    readonly screen: ScreenState;
+};
+interface CreateOptions extends ExecutionOptions {
+    readonly cwd?: string;
+    readonly command?: readonly string[];
+}
+interface RunOptions extends ExecutionOptions {
+    /** phux's own sentinel deadline, in seconds (distinct from local timeoutMs). */
+    readonly phuxTimeoutSeconds?: number;
+}
+interface AgentTargetOptions extends ExecutionOptions {
+    readonly target: string;
+}
+type SplitDirection = "horizontal" | "vertical";
+interface PlacementOptions {
+    readonly target?: string;
+    readonly split?: SplitDirection;
+    readonly ratio?: number;
+}
+interface SpawnOptions extends ExecutionOptions, PlacementOptions {
+    readonly satellite?: string;
+    readonly cwd?: string;
+    readonly command?: readonly string[];
+}
+interface LaunchOptions extends ExecutionOptions, PlacementOptions {
+    readonly cwd?: string;
+    readonly extra?: readonly string[];
+}
+interface SpatialOptions extends ExecutionOptions {
+    readonly direction?: SplitDirection;
+    readonly ratio?: number;
+}
+interface RenderedSnapshotOptions extends ExecutionOptions {
+    readonly session?: string;
+    readonly cols: number;
+    readonly rows: number;
+}
+interface AskOptions extends ExecutionOptions {
+    readonly id?: string;
+    readonly suggestions?: readonly string[];
+    readonly elapsedSeconds?: number;
+}
+type TerminalSignal = "interrupt" | "freeze" | "resume" | "terminate" | "kill";
+type TagAction = "ls" | "add" | "rm";
+interface WatchOptions extends ExecutionOptions {
+    readonly target: string;
+    /** Required collection window. The streaming CLI is always stopped after this bound. */
+    readonly durationMs: number;
+    readonly maxEvents: number;
+}
+interface WatchCollection {
+    readonly events: readonly WatchEvent[];
+    readonly truncated: boolean;
+    readonly ended: boolean;
+}
+interface PhuxProbe {
+    readonly available: boolean;
+    readonly version?: string;
+    readonly rawVersion?: string;
+    readonly reason?: string;
+}
+declare class PhuxCli {
+    readonly executable: string;
+    readonly socket: string | undefined;
+    private readonly cwd;
+    private readonly env;
+    private readonly runner;
+    private readonly maxStdoutBytes;
+    private readonly maxStderrBytes;
+    constructor(options?: PhuxCliOptions);
+    probe(options?: ExecutionOptions): Promise<PhuxProbe>;
+    ls(options?: ExecutionOptions): Promise<SessionList>;
+    /** Inventory panes and their owning session through the documented agent CLI projection. */
+    agentList(options?: ExecutionOptions): Promise<AgentStateList>;
+    create(name: string, options?: CreateOptions): Promise<CreateResult>;
+    spawn(options?: SpawnOptions): Promise<SpawnResult>;
+    launch(integration: string, options?: LaunchOptions): Promise<LaunchResult>;
+    insertPane(target: string, newPane: string, options?: SpatialOptions): Promise<InsertPaneResult>;
+    movePane(source: string, target: string, options?: SpatialOptions): Promise<MovePaneResult>;
+    swapPane(first: string, second: string, options?: ExecutionOptions): Promise<SwapPaneResult>;
+    /** Read one pane's public projection, including declared-record provenance. */
+    agentShow(options: AgentTargetOptions): Promise<AgentStateList>;
+    /** Write and parse the CLI's confirmed whole-record response. */
+    agentSet(target: string, record: AgentRecord, options?: ExecutionOptions): Promise<AgentRecord>;
+    /** Clear a declaration and require the CLI's confirmed tombstone response. */
+    agentClear(target: string, options?: ExecutionOptions): Promise<void>;
+    renderedSnapshot(options: RenderedSnapshotOptions): Promise<RenderedFrame>;
+    snapshot(options?: SnapshotOptions): Promise<ScreenState>;
+    wait(options?: WaitOptions): Promise<WaitOutcome>;
+    run(target: string, command: readonly string[], options?: RunOptions): Promise<RunResult>;
+    sendKeys(target: string, keys: readonly string[], options?: ExecutionOptions): Promise<void>;
+    kill(target: string, options?: ExecutionOptions): Promise<void>;
+    signal(target: string, signal: TerminalSignal, options?: ExecutionOptions): Promise<void>;
+    tag(action: TagAction, target: string, tags?: readonly string[], options?: ExecutionOptions): Promise<readonly TagRow[]>;
+    ask(target: string, question: string, options?: AskOptions): Promise<AskedEvent>;
+    watch(options: WatchOptions): Promise<WatchCollection>;
+    private jsonCommand;
+    private completed;
+    private execute;
+    private throwTermination;
+    private withSocket;
+    private pushSocket;
+}
+
+declare const PHUX_CONTEXT_VERSION: 1;
+interface PhuxAwarenessAdapter {
+    agentList(options?: ExecutionOptions): Promise<AgentStateList>;
+}
+interface PhuxContextIdentity {
+    readonly self?: string;
+    readonly selected?: string;
+}
+interface PhuxContextAwarenessOptions {
+    readonly enabled?: boolean;
+    readonly timeoutMs?: number;
+    readonly maxBytes?: number;
+    readonly maxPanes?: number;
+    readonly checkpointInterval?: number;
+}
+type PhuxContextKind = "checkpoint" | "delta";
+interface PhuxContextEmission {
+    readonly version: typeof PHUX_CONTEXT_VERSION;
+    readonly kind: PhuxContextKind;
+    readonly seq: number;
+    readonly text: string;
+}
+/**
+ * Per-host-session fleet projection. It emits one full checkpoint, then only
+ * changed suffix messages so provider prompt prefixes remain reusable.
+ */
+declare class PhuxContextAwareness {
+    private readonly adapter;
+    private readonly enabled;
+    private readonly timeoutMs;
+    private readonly maxBytes;
+    private readonly maxPanes;
+    private readonly checkpointInterval;
+    private readonly streams;
+    private readonly tails;
+    constructor(adapter: PhuxAwarenessAdapter, options?: PhuxContextAwarenessOptions);
+    next(streamId: string, identity?: PhuxContextIdentity, signal?: AbortSignal): Promise<PhuxContextEmission | null>;
+    /**
+     * Produce a compactor-only checkpoint. The next normal turn is forced to
+     * persist another checkpoint whether compaction succeeds or fails.
+     */
+    checkpoint(streamId: string, identity?: PhuxContextIdentity, signal?: AbortSignal): Promise<PhuxContextEmission | null>;
+    forceCheckpoint(streamId: string): void;
+    delete(streamId: string): void;
+    private serialized;
+    private emit;
+    private stream;
+    private project;
+}
+declare function contextAwarenessEnabled(value: string | undefined, fallback?: boolean): boolean;
+declare function normalizeTerminalIdentity(value: string | undefined): string | null;
+
+type JsonSchema = Readonly<Record<string, unknown>>;
+interface ToolContext {
+    readonly sessionID: string;
+    readonly agent: string;
+    readonly messageID: string;
+    readonly id: string;
+}
+interface ToolResult {
+    readonly content: string;
+    readonly metadata: PhuxToolMetadata;
+}
+interface PhuxToolDefinition<Input = never> {
+    readonly name: string;
+    readonly description: string;
+    readonly input: JsonSchema;
+    readonly execute: (input: Input, context: ToolContext) => Promise<ToolResult>;
+}
+
+declare const MAX_MODEL_BYTES: number;
+declare const MAX_MODEL_LINES = 200;
+declare const DEFAULT_SHORT_TIMEOUT_MS = 10000;
+interface PhuxToolMetadata {
+    readonly operation: "list" | "create" | "snapshot" | "send_keys" | "run" | "wait";
+    readonly target?: string;
+    readonly count?: number;
+    readonly exitCode?: number;
+    readonly durationMs?: number;
+    readonly outcome?: string;
+    readonly rows?: number;
+    readonly cols?: number;
+    readonly modelOutputTruncated?: boolean;
+    readonly phuxOutputTruncated?: boolean;
+}
+interface PhuxToolRuntime {
+    readonly cli: PhuxCli;
+    readonly environmentTarget?: string;
+    getSelectedTarget(): string | undefined;
+    selectTarget(target: string): void;
+    targetSelected?(context: ToolContext): void;
+}
+/** Build the six public OpenCode tools around one plugin-instance target selection. */
+declare function createPhuxTools(runtime: PhuxToolRuntime): Record<string, PhuxToolDefinition<any>>;
+declare function resolveTarget(explicit: string | undefined, runtime: Pick<PhuxToolRuntime, "getSelectedTarget" | "environmentTarget">): string;
+/** Bound terminal body text while preserving the header and explicit notices. */
+declare function boundedResult(header: string, body: string, phuxTruncated?: boolean): {
+    readonly text: string;
+    readonly truncated: boolean;
+};
+
+type OpenCodeLifecycleState = "idle" | "working";
+interface OpenCodeLifecycleAdapter {
+    agentShow(options: ExecutionOptions & {
+        readonly target: string;
+    }): Promise<AgentStateList>;
+    agentSet(target: string, record: AgentRecord, options?: ExecutionOptions): Promise<AgentRecord>;
+    agentClear(target: string, options?: ExecutionOptions): Promise<void>;
+}
+interface OpenCodeLifecycleOptions {
+    readonly cli?: OpenCodeLifecycleAdapter;
+    readonly timeoutMs?: number;
+    readonly onError?: (error: unknown) => void;
+    readonly target: () => string | undefined;
+}
+/**
+ * Best-effort metadata reporter driven only by documented session status,
+ * deletion, and plugin disposal signals.
+ */
+declare class OpenCodeLifecycle {
+    private readonly cli;
+    private readonly timeoutMs;
+    private readonly onError;
+    private readonly target;
+    private readonly states;
+    private readonly owned;
+    private tail;
+    private disposed;
+    constructor(options: OpenCodeLifecycleOptions);
+    /**
+     * A session is alive and should carry this plugin's identity.
+     *
+     * `state` is recorded for {@link targetSelected}'s fallback but is NOT
+     * written to the record: the server derives state from `rules/opencode.toml`,
+     * and declaring one would stand that detector down (phux-w7z2.38). The event
+     * still matters as a liveness trigger, which is why the signature keeps it.
+     */
+    observeState(sessionId: string, state: OpenCodeLifecycleState): Promise<void>;
+    /** A tool invocation is an honest working signal if no status event was seen yet. */
+    targetSelected(sessionId: string): Promise<void>;
+    deleteSession(sessionId: string): Promise<void>;
+    dispose(): Promise<void>;
+    settled(): Promise<void>;
+    private enqueue;
+    private publish;
+    private clearSession;
+    private clearOwned;
+    private execution;
+}
+interface OpenCodeLifecycleEvent {
+    readonly type: string;
+    readonly properties: Record<string, unknown>;
+}
+declare function handleLifecycleEvent(lifecycle: OpenCodeLifecycle, event: OpenCodeLifecycleEvent): Promise<void>;
+
+/** Plugin settings plus injectable seams for library and contract tests. */
+interface PhuxOpenCodeOptions {
+    readonly executable?: string;
+    readonly socket?: string;
+    readonly lifecycleTimeoutMs?: number;
+    readonly contextAwareness?: boolean;
+    readonly contextTimeoutMs?: number;
+    readonly cli?: PhuxCli;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly onLifecycleError?: (error: unknown) => void;
+}
+/** Build a V2 plugin with optional test-only defaults. */
+declare function createPhuxPlugin(defaults?: PhuxOpenCodeOptions): Plugin.Plugin;
+declare const PhuxPlugin: Plugin.Plugin;
+
+export { type AgentTargetOptions, type CreateOptions, DEFAULT_SHORT_TIMEOUT_MS, type ExecutionOptions, MAX_MODEL_BYTES, MAX_MODEL_LINES, OpenCodeLifecycle, type OpenCodeLifecycleAdapter, type OpenCodeLifecycleEvent, type OpenCodeLifecycleOptions, type OpenCodeLifecycleState, PhuxCli, type PhuxCliOptions, PhuxContextAwareness, type PhuxContextAwarenessOptions, type PhuxContextEmission, type PhuxContextIdentity, type PhuxOpenCodeOptions, PhuxPlugin, type PhuxProbe, type PhuxToolDefinition, type PhuxToolMetadata, type PhuxToolRuntime, type RunOptions, type SnapshotOptions, type ToolContext, type ToolResult, type WaitOptions, type WaitOutcome, boundedResult, contextAwarenessEnabled, createPhuxPlugin, createPhuxTools, PhuxPlugin as default, handleLifecycleEvent, normalizeTerminalIdentity, resolveTarget };