@agfpd/iapeer 0.1.0

package/src/launch/types.ts

@@ -0,0 +1,300 @@
+// Launch — the single session-bring-up primitive and the per-runtime adapter
+// contract. launch.launch is runtime-AGNOSTIC (env + argv + tmux new-session +
+// pipe-pane + self-TTL + boot + ready-gate + first-message delivery); the
+// runtime specifics (argv flags, system-prompt mechanism, boot dialogs, ready
+// markers, activity proxy, permission dialogs, resume) live behind RuntimeAdapter.
+//
+// Ownership split (blueprint §1, §7): launch = HOW to bring up ONE session;
+// lifecycle = WHEN / HOW MANY (wake/lock/reap/supervise). lifecycle.wakeOrSpawn
+// calls launch.launch; launch never decides whether or when to wake. The launch
+// path carries NO currency (no marketplace/plugin update) — that is install-time
+// (blueprint §0.6 fast-wake).
+//
+// This interface is FROZEN here (single author) so the per-runtime adapters can
+// be implemented independently against a known contract.
+
+import type { Intelligence, Runtime } from '../core/constants.ts'
+import type { PublicPeerSummary } from '../registry/index.ts'
+
+export type { PublicPeerSummary } from '../registry/index.ts'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// composeSystemPrompt — the layered Канал-A merge (docs/Сборка системного
+// промпта — слои и каналы.md). Four layers, general → specific (local overrides
+// global):
+//   1. System YAML (identity + host facts) — jq-GOLDEN, byte-for-byte.
+//   2. iapeer doctrine: ~/.iapeer/IAPEER.md (global) + <cwd>/.iapeer/IAPEER.md (local).
+//   3. Normalized peer registry (publicPeerSummary, exactly 5 fields).
+//   4. Plugin user-settings: every OTHER <DOMAIN>.md at the .iapeer/ root, global
+//      + local merged per domain. Custom files (SPAWNER_INSTRUCTIONS.md, …) flow
+//      in organically here — no special-casing.
+// composeSystemPrompt is a PURE renderer over already-gathered data; the FS
+// discovery lives in gatherPromptInput (mirrors the bash split: shell read the
+// files, the renderer just laid out bytes).
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** One Layer-4 domain: the global + local halves of a single `<DOMAIN>.md` pair
+ *  (either may be absent). `domain` is the filename stem, used only for stable
+ *  ordering — it is NOT emitted (the merge is organic, per the contract). */
+export interface PromptDomainBlock {
+  domain: string
+  /** ~/.iapeer/<DOMAIN>.md content (general). */
+  global?: string
+  /** <cwd>/.iapeer/<DOMAIN>.md content (specific — overrides global). */
+  local?: string
+}
+
+export interface ComposePromptInput {
+  personality: string
+  description: string
+  cwd: string
+  /** System facts (claude-start.sh:228-247). */
+  platform: string
+  osVersion: string
+  user: string
+  hostname: string
+  today: string
+  /** Layer 2 local: <cwd>/.iapeer/IAPEER.md content. '' when absent. */
+  peerDoctrine: string
+  /** Layer 2 global, OPTIONAL: ~/.iapeer/IAPEER.md content (sits between the YAML
+   *  block and the per-peer doctrine so per-peer overrides global). Existence-
+   *  gated: a present-but-empty file → '', an absent file → undefined. */
+  globalDoctrine?: string
+  /** Layer 3: the normalized peer registry. Empty/omitted → the layer emits
+   *  nothing (and the output stays byte-identical to the legacy YAML+doctrine). */
+  peers?: PublicPeerSummary[]
+  /** Layer 4: every non-IAPEER `<DOMAIN>.md` pair at the .iapeer/ root. Empty/
+   *  omitted → the layer emits nothing. */
+  pluginDomains?: PromptDomainBlock[]
+}
+
+/**
+ * Compose the merged system prompt, byte-for-byte equivalent to the claude-start
+ * jq pipeline:
+ *
+ *   ---\n
+ *   personality: <jq @json>\n
+ *   description: <jq @json>\n
+ *   peer-cwd: <jq @json>\n
+ *   platform: <jq @json>\n
+ *   os_version: <jq @json>\n
+ *   user: <jq @json>\n
+ *   hostname: <jq @json>\n
+ *   today: <jq @json>\n
+ *   ---\n
+ *   \n
+ *   [globalDoctrine + "\n"  — only when present]
+ *   peerDoctrine
+ *   [\n\n + registry section  — only when peers.length > 0]
+ *   [\n\n + merged domains    — only when pluginDomains is non-empty]
+ *
+ * Layers 1+2 are byte-for-byte the legacy jq output; layers 3+4 are appended
+ * (each as a `\n\n`-separated section) ONLY when they have content, so a peer
+ * with no registry and no extra domains produces the exact legacy bytes.
+ *
+ * Each YAML value is a JSON string literal (jq @json: JSON.stringify), which is
+ * also a valid YAML double-quoted scalar — safe against colons/quotes/newlines.
+ * The keys use hyphen `peer-cwd` and underscore `os_version` exactly as the bash.
+ */
+export type ComposeSystemPrompt = (input: ComposePromptInput) => string
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Launch spec + adapter config
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface LaunchAdapterConfig {
+  claudeBin: string
+  codexBin: string
+  /** telegram-runtime launch binary (router runtime). */
+  telegramBin?: string
+  /** notifier-runtime launch binary (router runtime, infra/always-on). */
+  notifierBin?: string
+}
+
+export interface LaunchSpec {
+  personality: string
+  runtime: Runtime
+  cwd: string
+  /** `<runtime>-<personality>` — the tmux session name + socket stem. */
+  identity: string
+  /** Socket path (`/tmp/tmux-iap-<identity>.sock`). */
+  socketPath: string
+  /** Composed system-prompt file path (tui runtimes that usesDoctrine). */
+  systemPromptFile?: string
+  /** Resume the newest transcript/session for this cwd (adapter validates). */
+  resume?: boolean
+  /** Pre-resolved resume ref (claude `--resume <uuid>`); set by resolveResume. */
+  resumeRef?: string
+  /** Free-form extra CLI args (PEER_START_ARGS). */
+  extraArgs?: string[]
+  /** Peer intelligence (artificial/natural/absent). Used to enforce an adapter's
+   *  intelligence gate at launch (telegram requires natural). Optional: a doctrine-
+   *  less throwaway may omit it, but an adapter that declares requiresIntelligence
+   *  then refuses (cannot confirm the required nature). */
+  intelligence?: Intelligence
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Delivery markers — the tui submit surface (owned by the adapter, 07.06 refactor)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Markers the transport submit path (submitIntoTui) needs to detect that a
+ * bracketed paste landed in the input row before pressing Enter. Contract refactor
+ * 07.06 (docs/Рантайм-адаптеры): the ADAPTER owns delivery markers — they moved out
+ * of the transport's hardcoded `PROMPT_GLYPHS = ['❯','›']` union so the generic
+ * submit logic carries NO runtime strings and a new runtime ships its own glyph
+ * with its adapter, not by editing transport.
+ */
+export interface DeliveryMarkers {
+  /** Glyph(s) at column 0 of the rendered input-prompt row (claude '❯', codex '›').
+   *  submitIntoTui locates the prompt row by these. A router has no submit surface
+   *  → empty array. */
+  promptGlyphs: string[]
+  /** Extra "bracketed paste landed" indicators beyond the envelope's own tail-marker
+   *  (claude '[Pasted text' / '[Image #'). Optional — when absent the tail-marker is
+   *  the sole landed-signal. */
+  pastePatterns?: RegExp[]
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Control commands (Ф-E, docs/Control-команды). The SECOND daemon channel: an
+// in-session control command (interrupt / compact) is mapped by the target's adapter
+// to a tmux send-keys sequence and performed UNCONDITIONALLY (immediate, NOT gated on
+// ready — the point is to interrupt / drive, not to wait). System commands (list /
+// status) are the daemon's own and do not reach the adapter.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** An abstract in-session control command (`interrupt`, `compact`, runtime-specific). */
+export interface ControlCommand {
+  name: string
+  args?: readonly string[]
+}
+
+/** The runtime mechanism for a control command: a sequence of `tmux send-keys`
+ *  arg-lists, performed IN ORDER on the target session. */
+export interface ControlPlan {
+  /** Each inner array is one `tmux send-keys -t <addr>` call's trailing args
+   *  (e.g. ['Escape'] or ['-l', '/compact'] then ['Enter']). */
+  sequence: string[][]
+  /** Pause (ms) between sequence steps — e.g. typed text must settle before Enter. */
+  stepDelayMs?: number
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// RuntimeAdapter — per-runtime "HOW to launch / observe one session"
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface RuntimeAdapter {
+  runtime: Runtime
+  /** 'tui' (claude/codex — pane boot/ready/dialogs) | 'router' (telegram — no TUI phases). */
+  kind: 'tui' | 'router'
+  /** Does this runtime consume a composed system-prompt doctrine? (tui yes, router no). */
+  usesDoctrine: boolean
+
+  /**
+   * Delivery markers for the transport submit path (submitIntoTui) — the input-
+   * prompt glyph(s) and optional "paste landed" patterns. The adapter OWNS them
+   * (07.06 refactor): transport reads them from here instead of a hardcoded glyph
+   * union. A router declares `{ promptGlyphs: [] }` (no submit surface).
+   */
+  deliveryMarkers: DeliveryMarkers
+
+  /**
+   * If set, launch REFUSES unless the peer's intelligence equals this value
+   * (fail-loud). telegram → 'natural' — it is a human channel; launching an
+   * artificial/absent peer on it is a category error (PP held a FATAL guard in two
+   * places). Most adapters omit it (no nature gate). Source of intelligence →
+   * docs/Идентичность; enforced by the launch primitive against LaunchSpec.intelligence.
+   */
+  requiresIntelligence?: Intelligence
+
+  /**
+   * Build the runtime argv: binary + flags, wiring systemPromptFile per-runtime
+   *  - claude: `--dangerously-skip-permissions [--disallowedTools …] --system-prompt-file <f> [extra]`
+   *  - codex:  `[resume --last] --no-alt-screen -C <cwd> -c model_instructions_file=<f> --dangerously-bypass-approvals-and-sandbox [extra]`
+   *  - telegram: `telegram-runtime run …` (no doctrine).
+   * NO currency on this path.
+   */
+  buildArgv(spec: LaunchSpec, cfg: LaunchAdapterConfig): string[]
+
+  /**
+   * If a known startup dialog is visible in `pane`, return the tmux send-keys
+   * args to clear it (e.g. ['Enter'] or ['Down','Enter']); else null. (tui only).
+   */
+  bootDialogKeys(pane: string): string[] | null
+
+  /** Is the input surface ready for the first message? (tui: ready marker present
+   *  AND startup dialogs gone). Router runtimes return true (no input surface). */
+  isInputReady(pane: string): boolean
+
+  /** Newest activity-proxy mtime for the ready-gate AND idle accounting:
+   *  claude transcript / codex session jsonl mtime; null for a router (no proxy). */
+  newestActivityMtime(cwd: string): number | null
+
+  /** Is a permission/approval dialog open in the pane (headless autopilot)? */
+  permissionDialogActive(pane: string): boolean
+  /** tmux send-keys args to affirm a permission dialog (claude ['Enter'];
+   *  codex ['Down','Enter'] to pick "allow for session"). */
+  permissionDialogKeys(): string[]
+
+  /** Resume preflight — validate a resume request fail-loud (never silent fresh).
+   *  Returns the resolved ref (claude uuid) or ok:false with a reason. */
+  resolveResume(cwd: string): { ok: boolean; ref?: string; reason?: string }
+
+  /**
+   * Map an abstract in-session control command to this runtime's mechanism (a tmux
+   * send-keys sequence — ControlPlan), or null when the runtime does not support it
+   * (the daemon/CLI surfaces an explicit refusal). Ф-E, docs/Control-команды:
+   *   - tui (claude/codex): `interrupt` → ['Escape'] (claude ×1; codex ×1-2, snapped
+   *     live), `compact` → type '/compact' then Enter. Declares the supported set.
+   *   - router (telegram/notifier): no TUI turn → null for everything (refuse).
+   * Performed UNCONDITIONALLY (immediate, not ready-gated) — the point is to
+   * interrupt / drive a possibly-stuck session, exactly when normal delivery wouldn't.
+   */
+  executeControl(command: ControlCommand): ControlPlan | null
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// launch primitive
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface LaunchConfig extends LaunchAdapterConfig {
+  sockDir: string
+  bootDeadlineSecs: number
+  readyGateSecs: number
+  maxAgeSecs: number
+  /** Log dir for pipe-pane output. */
+  logDir: string
+  env?: NodeJS.ProcessEnv
+  /**
+   * Always-on bring-up (infra runtimes held by launchd KeepAlive): SKIP the
+   * session self-TTL so the session is not auto-killed at maxAgeSecs. The TTL is
+   * a warm-on-demand zombie bound; an always-on session's lifecycle is owned by
+   * launchd (KeepAlive respawns it), so the self-kill timer must not fire.
+   */
+  alwaysOn?: boolean
+}
+
+export interface LaunchResult {
+  status: 'READY' | 'FAILED'
+  identity: string
+  process_address: string
+  reason?: string
+}
+
+/**
+ * Bring up ONE session: pre-clean stale tmux server → tmux new-session -d with
+ * adapter.buildArgv → pipe-pane → session self-TTL → boot (answer dialogs via
+ * adapter, wait for adapter.isInputReady, deliver the first message via
+ * send-keys -l) → ready-gate (adapter.newestActivityMtime strictly advances).
+ * Runtime-agnostic; all specifics come from the adapter. Returns READY/FAILED.
+ * `firstMessage` (the task / routed envelope) is delivered as the boot message;
+ * a router runtime skips the TUI boot/ready phases.
+ */
+export type LaunchFn = (
+  spec: LaunchSpec,
+  adapter: RuntimeAdapter,
+  firstMessage: string,
+  cfg: LaunchConfig,
+) => Promise<LaunchResult>