@yaag/runtime 0.1.0

package/src/connection.ts

@@ -0,0 +1,123 @@
+import { YaagError } from "./errors.ts";
+import type { AgentTransport, Frame } from "./transport.ts";
+
+/** The useful part of a `response` frame, once narrowed. */
+export interface CommandResponse {
+  readonly success: boolean;
+  readonly error: string | null;
+  readonly data: Record<string, unknown> | null;
+}
+
+/** Dialog methods block the Agent until answered (ADR-0012). */
+const DIALOG_METHODS = new Set(["select", "confirm", "input", "editor"]);
+
+/**
+ * One conversation with an Agent over the transport seam: correlates commands
+ * with their responses by id, cancels dialogs, and hands every other frame to
+ * the Ask in flight.
+ *
+ * Lives above the seam, so it knows nothing about processes.
+ */
+export class Connection {
+  readonly #transport: AgentTransport;
+  readonly #agent: string;
+  readonly #pending = new Map<string, (response: CommandResponse) => void>();
+  readonly #closed: Promise<void>;
+  #observer: ((frame: Frame) => void) | null = null;
+  #dead = false;
+  #nextId = 0;
+
+  constructor(transport: AgentTransport, agent: string) {
+    this.#transport = transport;
+    this.#agent = agent;
+    this.#closed = this.#read();
+  }
+
+  /** True once the Agent's frame stream has ended: the Handle is permanently dead. */
+  get dead(): boolean {
+    return this.#dead;
+  }
+
+  /** Resolves when the Agent's frame stream ends. Never rejects. */
+  get closed(): Promise<void> {
+    return this.#closed;
+  }
+
+  /** Routes non-response frames to a listener, replacing any previous one. */
+  observe(listener: ((frame: Frame) => void) | null): void {
+    this.#observer = listener;
+  }
+
+  /**
+   * Sends one command and resolves with its id-correlated response.
+   * Rejects with AGENT_DIED if the Agent dies first.
+   */
+  command(frame: Frame): Promise<CommandResponse> {
+    if (this.#dead) return Promise.reject(this.#deadError());
+    const id = `yaag-${this.#nextId++}`;
+    const response = new Promise<CommandResponse>((resolve) => {
+      this.#pending.set(id, resolve);
+    });
+    this.#transport.send({ ...frame, id });
+    // Responses can arrive after agent_settled, so nothing here waits on order.
+    return Promise.race([
+      response,
+      this.#closed.then(() => {
+        throw this.#deadError();
+      }),
+    ]);
+  }
+
+  /** Never rejects: a broken stream is a dead Agent, not an unhandled error. */
+  async #read(): Promise<void> {
+    try {
+      for await (const frame of this.#transport.frames()) {
+        this.#dispatch(frame);
+      }
+    } finally {
+      this.#dead = true;
+      this.#pending.clear();
+    }
+  }
+
+  #dispatch(frame: Frame): void {
+    if (frame.type === "response") {
+      const id = typeof frame.id === "string" ? frame.id : null;
+      const resolve = id === null ? undefined : this.#pending.get(id);
+      if (id !== null && resolve) {
+        this.#pending.delete(id);
+        resolve(toResponse(frame));
+      }
+      return;
+    }
+    if (frame.type === "extension_ui_request") {
+      this.#answerDialog(frame);
+      return;
+    }
+    this.#observer?.(frame);
+  }
+
+  /**
+   * An unanswered dialog wedges the Agent forever — the observed `confirm`
+   * carried no `timeout` field (ADR-0012). Cancelling is what Esc does.
+   */
+  #answerDialog(frame: Frame): void {
+    const method = typeof frame.method === "string" ? frame.method : "";
+    if (!DIALOG_METHODS.has(method)) return;
+    if (typeof frame.id !== "string") return;
+    this.#transport.send({ type: "extension_ui_response", id: frame.id, cancelled: true });
+  }
+
+  #deadError(): YaagError {
+    return new YaagError("AGENT_DIED", `agent "${this.#agent}" is no longer running`, this.#agent);
+  }
+}
+
+function toResponse(frame: Frame): CommandResponse {
+  const data: unknown = frame.data;
+  return {
+    success: frame.success === true,
+    error: typeof frame.error === "string" ? frame.error : null,
+    data: typeof data === "object" && data !== null ? { ...data } : null,
+  };
+}

package/src/define-agent.ts

@@ -0,0 +1,83 @@
+import type { AskOptions, ThinkingLevel } from "./types.ts";
+
+export type { ThinkingLevel } from "./types.ts";
+
+/** What `defineAgent` is given: the policy of one Agent, never its topology. */
+export interface AgentConfig {
+  /** Stable identity, used in every Lifecycle Event and log line. */
+  readonly name: string;
+  /** System prompt text appended to pi's own, unless `overrideSystemPrompt`. */
+  readonly prompt?: string;
+  /** Replace pi's system prompt with `prompt` instead of appending to it. */
+  readonly overrideSystemPrompt?: boolean;
+  /** Model id handed to `pi --model`. Unset = pi's default. */
+  readonly model?: string;
+  /** Thinking budget for the Agent's turns. */
+  readonly thinking?: ThinkingLevel;
+  /** Allow-list of tool names. Unset = pi's default tool set. */
+  readonly tools?: readonly string[];
+  /** Deny-list of tool names, applied after `tools`. */
+  readonly disallowedTools?: readonly string[];
+  /** Allow-list of skill names. Unset = pi's default skill set. */
+  readonly skills?: readonly string[];
+  /** Deny-list of skill names, applied after `skills`. */
+  readonly disallowedSkills?: readonly string[];
+  /** Ask options applied to every Ask on this Agent unless overridden per call. */
+  readonly askDefaults?: AskOptions;
+}
+
+/** Not exported, so the config is unreachable outside this module. */
+const definition = Symbol("yaag.agent");
+
+/** Opaque, deep-frozen result of `defineAgent`. */
+export interface AgentDefinition {
+  readonly [definition]: AgentConfig;
+}
+
+const arrayFields = ["tools", "disallowedTools", "skills", "disallowedSkills"] as const;
+
+/**
+ * Declares an Agent Definition: reusable policy, independent of where it runs.
+ *
+ * Throws a TypeError when `name` is missing or blank, or when `cwd`/`worktree`
+ * appear — those are topology, chosen at spawn time, not baked into a definition.
+ * The config is defensively copied and deep-frozen, so later mutation of the
+ * caller's arrays cannot change the definition.
+ */
+export function defineAgent(config: AgentConfig): AgentDefinition {
+  if (typeof config.name !== "string" || config.name.trim() === "") {
+    throw new TypeError("defineAgent: name is required and must be non-empty");
+  }
+  if ("cwd" in config || "worktree" in config) {
+    throw new TypeError(
+      "defineAgent: cwd and worktree are topology concerns — set them at spawn time, not in the definition",
+    );
+  }
+  const copy: { -readonly [K in keyof AgentConfig]: AgentConfig[K] } = { ...config };
+  for (const field of arrayFields) {
+    const value = config[field];
+    if (value !== undefined) copy[field] = Object.freeze(value.slice());
+  }
+  if (config.askDefaults !== undefined) {
+    copy.askDefaults = Object.freeze({ ...config.askDefaults });
+  }
+  return Object.freeze({ [definition]: Object.freeze(copy) });
+}
+
+/** True only for values produced by `defineAgent`. */
+export function isAgentDefinition(value: unknown): value is AgentDefinition {
+  return typeof value === "object" && value !== null && definition in value;
+}
+
+/**
+ * Recovers the config behind an Agent Definition.
+ * Throws a TypeError when the value did not come from `defineAgent`.
+ */
+export function agentDefinitionConfig(value: AgentDefinition): AgentConfig;
+export function agentDefinitionConfig(value: unknown): AgentConfig;
+export function agentDefinitionConfig(value: unknown): AgentConfig {
+  if (!isAgentDefinition(value)) {
+    throw new TypeError("not an Agent Definition — build it with defineAgent({ name })");
+  }
+  return value[definition];
+}

package/src/define-run.ts

@@ -0,0 +1,69 @@
+import type { Static, TSchema } from "typebox";
+import type { RunContext } from "./run-context.ts";
+
+/** What `defineRun` is given. */
+export interface ProgramDefinition<Args = unknown, Result = unknown> {
+  readonly name?: string;
+  readonly description?: string;
+  /** Optional Typebox contract for arguments delivered to `run`. */
+  readonly args?: TSchema;
+  readonly run: (ctx: RunContext<Args>) => Result | Promise<Result>;
+}
+
+type SchemaProgramDefinition<Schema extends TSchema, Result> = Omit<
+  ProgramDefinition<Static<Schema>, Result>,
+  "args"
+> & {
+  readonly args: Schema;
+};
+
+type SchemalessProgramDefinition<Args, Result> = ProgramDefinition<Args, Result> & {
+  readonly args?: never;
+};
+
+/** Not exported, so the definition is unreachable outside this module. */
+const definition = Symbol("yaag.program");
+
+/** Opaque result of `defineRun`. Must be the module's default export. */
+export interface OrchestrationProgram<Args = unknown, Result = unknown> {
+  readonly [definition]: ProgramDefinition<Args, Result>;
+}
+
+/**
+ * Declares an Orchestration Program with arguments inferred from its Typebox schema.
+ *
+ * The returned value is opaque: exporting anything else as default is a compile
+ * error rather than a runtime "no program found".
+ */
+export function defineRun<Schema extends TSchema, Result>(
+  program: SchemaProgramDefinition<Schema, Result>,
+): OrchestrationProgram<Static<Schema>, Result>;
+/** Declares an Orchestration Program without an argument schema. */
+export function defineRun<Args = unknown, Result = unknown>(
+  program: SchemalessProgramDefinition<Args, Result>,
+): OrchestrationProgram<Args, Result>;
+export function defineRun<Args, Result>(
+  program: ProgramDefinition<Args, Result>,
+): OrchestrationProgram<Args, Result> {
+  return { [definition]: program };
+}
+
+/** True only for values produced by `defineRun`. */
+export function isOrchestrationProgram(value: unknown): value is OrchestrationProgram {
+  return typeof value === "object" && value !== null && definition in value;
+}
+
+/**
+ * Recovers the definition behind a program.
+ * Throws a TypeError when the value did not come from `defineRun`.
+ */
+export function programDefinition<Args, Result>(
+  value: OrchestrationProgram<Args, Result>,
+): ProgramDefinition<Args, Result>;
+export function programDefinition(value: unknown): ProgramDefinition;
+export function programDefinition(value: unknown): ProgramDefinition {
+  if (!isOrchestrationProgram(value)) {
+    throw new TypeError("not an Orchestration Program — export defineRun({ run }) as default");
+  }
+  return value[definition];
+}

package/src/errors.ts

@@ -0,0 +1,115 @@
+/** Which soft Ask budget was exhausted. */
+export type AskLimitKind = "turns" | "toolCalls" | "durationMs";
+
+/** The recorded result when yaag aborts an Ask after a soft budget is exhausted. */
+export interface AskLimitOutcome {
+  readonly kind: AskLimitKind;
+  readonly count: number;
+}
+
+/** The recorded result when yaag rejects an Ask because no frame arrived within `idleMs`. */
+export interface AskStalledOutcome {
+  /** The configured silence threshold that tripped. */
+  readonly idleMs: number;
+  /** True when abort failed to settle the Agent and yaag killed the process. */
+  readonly destructive: boolean;
+}
+
+/** Recoverable result when all structured-output correction efforts are exhausted. */
+export interface AskInvalidOutputOutcome {
+  /** Corrective steers sent before aborting this Ask. */
+  readonly steeringEfforts: number;
+  /** Final extraction or TypeBox diagnostics, localized to JSON paths. */
+  readonly errors: readonly string[];
+}
+
+/** Why an Ask, spawn, or Run failed. Programs may branch on this; most won't. */
+export type YaagErrorCode =
+  | "AGENT_FAILED" // turn settled with stopReason error/aborted, or empty text
+  | "AGENT_DIED" // process exited with an Ask pending
+  | "AGENT_BUSY" // concurrent ask() on one Handle
+  | "ASK_TIMEOUT" // timeoutMs elapsed
+  | "ASK_LIMIT" // soft Ask budget exceeded after grace
+  | "ASK_STALLED" // no frame arrived within idleMs; escalated by abort, then kill
+  | "ASK_INVALID_OUTPUT" // settled text could not be extracted or satisfy outputSchema
+  | "ARGS_INVALID" // arguments failed schema validation before the Run started
+  | "OPTIONS_CONFLICT" // incompatible Run options were supplied
+  | "REPLAY_DIVERGED" // replayed program differed from its Cassette
+  | "RESUME_REFUSED" // resume metadata is absent or the recorded tree moved
+  | "RUN_CLOSED" // spawn was requested after the Run began settling
+  | "RUN_STOPPED" // the Run's abort signal fired before the program completed
+  | "WORKTREE_REFUSED" // base cwd is not a clean Git repository
+  | "SPAWN_FAILED"; // pi failed to start, e.g. unknown model
+
+/** The single error class of the runtime (ADR-0003). */
+export class YaagError extends Error {
+  readonly code: YaagErrorCode;
+  /** Agent name, when the error concerns one. */
+  readonly agent?: string;
+  /** Exhausted soft Ask budget, present only for `ASK_LIMIT`. */
+  readonly limit?: AskLimitKind;
+  /** Count observed when the soft Ask budget first tripped. */
+  readonly count?: number;
+  /** Silence threshold that tripped, present only for `ASK_STALLED`. */
+  readonly idleMs?: number;
+  /** True when an `ASK_STALLED` escalation had to kill the Agent. */
+  readonly destructive?: boolean;
+  /** Number of corrective output steers sent, present only for `ASK_INVALID_OUTPUT`. */
+  readonly steeringEfforts?: number;
+  /** Localized extraction or schema errors, present only for `ASK_INVALID_OUTPUT`. */
+  readonly errors?: readonly string[];
+
+  constructor(
+    code: YaagErrorCode,
+    message: string,
+    agent?: string,
+    options?: AskLimitOutcome | AskStalledOutcome | AskInvalidOutputOutcome,
+  ) {
+    super(message);
+    this.name = "YaagError";
+    this.code = code;
+    if (agent !== undefined) this.agent = agent;
+    if (options !== undefined && "kind" in options) {
+      this.limit = options.kind;
+      this.count = options.count;
+    }
+    if (options !== undefined && "idleMs" in options) {
+      this.idleMs = options.idleMs;
+      this.destructive = options.destructive;
+    }
+    if (options !== undefined && "steeringEfforts" in options) {
+      this.steeringEfforts = options.steeringEfforts;
+      this.errors = options.errors;
+    }
+  }
+}
+
+/** Builds the runtime's uniform agent-scoped error message. */
+export function agentError(agent: string, code: YaagErrorCode, message: string): YaagError {
+  return new YaagError(code, `agent "${agent}": ${message}`, agent);
+}
+
+/** The ASK_LIMIT rejection for one exhausted soft budget. */
+export function askLimitError(agent: string, outcome: AskLimitOutcome): YaagError {
+  return new YaagError(
+    "ASK_LIMIT",
+    `agent "${agent}": ${outcome.kind} limit reached at ${outcome.count}`,
+    agent,
+    outcome,
+  );
+}
+
+/** The ASK_STALLED rejection for one tripped idle watch. */
+export function askStalledError(agent: string, outcome: AskStalledOutcome): YaagError {
+  return new YaagError(
+    "ASK_STALLED",
+    `agent "${agent}": no frame for ${outcome.idleMs}ms${outcome.destructive ? " (killed)" : ""}`,
+    agent,
+    outcome,
+  );
+}
+
+/** Narrows an unknown rejection reason to a YaagError. */
+export function isYaagError(value: unknown): value is YaagError {
+  return value instanceof YaagError;
+}

package/src/events.ts

@@ -0,0 +1,143 @@
+/**
+ * Lifecycle Events (ADR-0006): a closed set of flat records, emitted above the
+ * transport seam. Live-only frame observers may add richer events than a
+ * Cassette replay produces; replay intentionally omits that observation data.
+ * Playback Asks still emit normal start/end events, but intentionally omit live
+ * activity, output, and usage observations. v0 renders them as stderr lines; the
+ * dedicated fd arrives with the extension.
+ */
+import type { TokenBreakdown, WorktreeResolution } from "./transport.ts";
+
+/** A settled Run's terminal outcome (ADR-0022). `paused` arrives with the pause slice. */
+export type RunOutcome = "completed" | "failed" | "stopped" | "paused";
+
+/** The current, Ask-scoped observer projection derived from Agent frames. */
+export type AgentActivity =
+  | { readonly type: "thinking" }
+  | { readonly type: "writing" }
+  | { readonly type: "tool"; readonly name: string; readonly argsGist: string }
+  | { readonly type: "compacting" }
+  | { readonly type: "retrying"; readonly attempt: number; readonly max: number };
+
+/** The assistant stream channel carried by an additive `ask_output` event. */
+export type AskOutputChannel = "text" | "thinking";
+
+/** The lifecycle state of one Nested Node, as decoded from its parent's frames. */
+export type NodeState = "running" | "exited" | "failed";
+
+/** Accounting a nesting tool reports for one Nested Node; both fields are optional facts. */
+export interface NodeUsage {
+  readonly tokens?: TokenBreakdown;
+  readonly cost?: number;
+}
+
+export type LifecycleEventBody =
+  | { readonly type: "run_start"; readonly program: string }
+  | {
+      readonly type: "agent_spawn";
+      readonly agent: string;
+      readonly model: string;
+      readonly cwd: string;
+      /** Present only when the Agent was spawned into a worktree. */
+      readonly branch?: string;
+      /**
+       * pi's persisted session file for this Agent, when the startup handshake
+       * reported one. A path is not a prompt payload, so it may ride the wire
+       * (ticket 09); a Peek reads this file to render the transcript. Absent for
+       * Cassette-playback Agents and events from older CLIs.
+       */
+      readonly sessionFile?: string;
+    }
+  | {
+      readonly type: "ask_start";
+      readonly agent: string;
+      readonly index: number;
+      /** First non-blank prompt line, whitespace-collapsed, ≤ PROMPT_GIST_MAX_CHARS. */
+      readonly promptGist: string;
+      /** Full prompt length; the prompt itself never rides the wire (ticket 09). */
+      readonly promptChars: number;
+      /** Present only when this individual Ask was served from Cassette playback. */
+      readonly replayed?: true;
+    }
+  | {
+      readonly type: "ask_activity";
+      readonly agent: string;
+      readonly index: number;
+      readonly activity: AgentActivity;
+    }
+  | {
+      readonly type: "ask_output";
+      readonly agent: string;
+      readonly index: number;
+      readonly channel: AskOutputChannel;
+      readonly text: string;
+    }
+  | {
+      /**
+       * A bounded snapshot of one Nested Node. It is the only nested-node event:
+       * there is no per-node spawn/ask/exit mirroring (spec §3). Unlike
+       * `ask_activity` and `ask_output`, it is re-derived on Cassette replay,
+       * because it decodes recorded Agent frames only (ADR-0006, ADR-0013).
+       */
+      readonly type: "node_update";
+      readonly agent: string;
+      /** Node identity in the grammar `name(:askIndex(/childName…))`. */
+      readonly path: string;
+      readonly state: NodeState;
+      /** One line, ≤ NODE_GIST_MAX_CHARS; never a prompt (ticket 09). */
+      readonly activityGist?: string;
+      readonly usage?: NodeUsage;
+    }
+  | {
+      readonly type: "ask_end";
+      readonly agent: string;
+      readonly index: number;
+      readonly durationMs: number;
+      readonly ok: boolean;
+      /** Largest inter-frame silence during this Ask; absent during Cassette playback. */
+      readonly maxFrameGapMs?: number;
+    }
+  | {
+      readonly type: "agent_usage";
+      readonly agent: string;
+      /** Cumulative assistant-completion usage observed so far. */
+      readonly tokens: TokenBreakdown;
+      /** Cumulative assistant-completion cost observed so far. */
+      readonly cost: number;
+    }
+  | {
+      readonly type: "agent_exit";
+      readonly agent: string;
+      readonly tokens: TokenBreakdown | null;
+      readonly cost: number | null;
+      /** Cost is a floor, not a total: the Agent was killed mid-Ask (ADR-0012). */
+      readonly incomplete: boolean;
+      /** Surviving worktree identity, present only for worktree Agents. */
+      readonly worktree?: WorktreeResolution;
+    }
+  | {
+      readonly type: "run_end";
+      readonly ok: boolean;
+      /** Terminal outcome (ADR-0022); the invariant is `ok === (outcome === "completed")`. */
+      readonly outcome: RunOutcome;
+      readonly durationMs: number;
+      readonly cost: number;
+      /** Summed component-wise; null when any Agent's usage was unknown. */
+      readonly tokens: TokenBreakdown | null;
+      /** At least one Agent's cost was an undercount. */
+      readonly incomplete: boolean;
+      /** Largest inter-frame silence across every Ask; 0 when nothing was measured. */
+      readonly worstFrameGapMs: number;
+    };
+
+/**
+ * A Lifecycle Event as observers see it: the body plus `at` — epoch-ms wall
+ * clock, stamped once in the Orchestrator's sink wrapper, never per emitter.
+ */
+export type LifecycleEvent = LifecycleEventBody & { readonly at: number };
+
+/** Where emitters inside a Run report Lifecycle Event bodies, pre-stamp. */
+export type EventSink = (event: LifecycleEventBody) => void;
+
+/** Where a Run reports its stamped Lifecycle Events. */
+export type StampedEventSink = (event: LifecycleEvent) => void;

package/src/extension-package.ts

@@ -0,0 +1,88 @@
+import { readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import type { ExtensionSource, InstalledExtensionSource } from "./extension-source.ts";
+
+/** Roots searched for an already-installed pi package, project before user. */
+export interface ExtensionInstallRoots {
+  /** Agent working directory holding `.pi/npm` and `.pi/git`; defaults to `process.cwd()`. */
+  readonly projectRoot?: string;
+  /** pi user config directory; defaults to `~/.pi/agent`. */
+  readonly userConfigDir?: string;
+}
+
+/**
+ * Expands an installed pi package into its declared extension entry files.
+ *
+ * Resolves the project install before the user install, then reads the package
+ * manifest's `pi.extensions` array in declaration order. Returns `undefined`
+ * when the package is not installed, so the caller can hand the raw specifier
+ * to pi and let it temp-install (docs/packages.md).
+ */
+export async function resolveInstalledExtension(
+  source: ExtensionSource,
+  roots: ExtensionInstallRoots = {},
+): Promise<readonly string[] | undefined> {
+  if (source.kind === "path") return undefined;
+  for (const directory of candidateDirectories(source, roots)) {
+    if (await isDirectory(directory)) return await entryPoints(directory);
+  }
+  return undefined;
+}
+
+function candidateDirectories(
+  source: InstalledExtensionSource,
+  roots: ExtensionInstallRoots,
+): readonly string[] {
+  const projectRoot = resolve(roots.projectRoot ?? process.cwd());
+  const userConfigDir = roots.userConfigDir ?? join(homedir(), ".pi", "agent");
+  const suffix =
+    source.kind === "npm"
+      ? join("npm", "node_modules", source.packageName)
+      : join("git", source.host, source.owner, source.repo);
+  return [join(projectRoot, ".pi", suffix), join(userConfigDir, suffix)];
+}
+
+async function entryPoints(directory: string): Promise<readonly string[]> {
+  const manifest = await readManifest(join(directory, "package.json"));
+  const declared = manifest?.pi?.extensions;
+  if (declared !== undefined && declared.length > 0) {
+    return declared.map((entry) => resolve(directory, entry));
+  }
+  if (typeof manifest?.main === "string") return [resolve(directory, manifest.main)];
+  return [join(directory, "index.ts")];
+}
+
+interface PackageManifest {
+  readonly main?: string;
+  readonly pi?: { readonly extensions?: readonly string[] };
+}
+
+async function readManifest(path: string): Promise<PackageManifest | undefined> {
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch {
+    return undefined;
+  }
+  const value: unknown = JSON.parse(text);
+  if (typeof value !== "object" || value === null) return undefined;
+  const main = "main" in value && typeof value.main === "string" ? value.main : undefined;
+  return { ...(main === undefined ? {} : { main }), pi: { extensions: readExtensions(value) } };
+}
+
+function readExtensions(value: object): readonly string[] | undefined {
+  if (!("pi" in value) || typeof value.pi !== "object" || value.pi === null) return undefined;
+  const pi: object = value.pi;
+  if (!("extensions" in pi) || !Array.isArray(pi.extensions)) return undefined;
+  const entries = pi.extensions.filter((entry): entry is string => typeof entry === "string");
+  return entries.length === 0 ? undefined : entries;
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/src/extension-paths.ts

@@ -0,0 +1,66 @@
+import { lstat } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { type ExtensionInstallRoots, resolveInstalledExtension } from "./extension-package.ts";
+import { parseExtensionSource } from "./extension-source.ts";
+
+/** Inputs that decide how a declaration becomes a launch-ready `-e` argument. */
+export interface ExtensionResolutionOptions extends ExtensionInstallRoots {
+  /** Orchestration Program source path, required by relative declarations. */
+  readonly programFile?: string;
+}
+
+/**
+ * Resolves declared extensions into launch-ready `pi -e` arguments before transport opening.
+ *
+ * Filesystem declarations are resolved against the Orchestration Program directory and
+ * checked for existence. `npm:`/`git:` specifiers expand to the entry points of the
+ * already-installed package (project install shadows the user install); an uninstalled
+ * specifier passes through verbatim so pi temp-installs it. Results retain declaration
+ * order. Rejects missing paths and a relative declaration without `programFile`.
+ */
+export async function resolveExtensionPaths(
+  declarations: readonly string[],
+  options: ExtensionResolutionOptions = {},
+): Promise<readonly string[]> {
+  const paths: string[] = [];
+  for (const declaration of declarations) {
+    paths.push(...(await resolveOne(declaration, options)));
+  }
+  return paths;
+}
+
+async function resolveOne(
+  declaration: string,
+  options: ExtensionResolutionOptions,
+): Promise<readonly string[]> {
+  const source = parseExtensionSource(declaration);
+  if (source.kind === "path") {
+    const path = resolveDeclaration(declaration, options.programFile);
+    await requireExists(declaration, path);
+    return [path];
+  }
+  const installed = await resolveInstalledExtension(source, options);
+  if (installed === undefined) return [declaration];
+  for (const path of installed) await requireExists(declaration, path);
+  return installed;
+}
+
+function resolveDeclaration(declaration: string, programFile: string | undefined): string {
+  if (isAbsolute(declaration)) return declaration;
+  if (programFile === undefined) {
+    throw new Error(`relative extension "${declaration}" requires RunOptions.programFile`);
+  }
+  return resolve(dirname(programFile), declaration);
+}
+
+async function requireExists(declaration: string, path: string): Promise<void> {
+  try {
+    await lstat(path);
+  } catch (error) {
+    // Only absence is translated; permission errors and the like surface as-is.
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
+    if (declaration === path) throw new Error(`extension "${path}" does not exist`);
+    throw new Error(`extension "${declaration}" does not exist at "${path}"`);
+  }
+}