@yaag/runtime 0.1.0

package/src/skill-probe.ts

@@ -0,0 +1,247 @@
+/** One enabled skill reported by pi's `get_commands` response. */
+export interface DiscoveredSkill {
+  readonly name: string;
+  readonly path: string;
+  /** True when an extension injects the skill after `--no-skills` is processed. */
+  readonly extensionInjected: boolean;
+}
+
+/** Cwd-scoped skill discovery seam, separate from long-lived Agent transports. */
+export interface SkillProbeFactory {
+  probe(cwd: string): Promise<readonly DiscoveredSkill[]>;
+}
+
+/** The stdin operations owned by one short-lived skill discovery process. */
+export interface SkillProbeStdin {
+  write(input: string): void;
+  flush(): void;
+  end(): void;
+}
+
+/**
+ * The short-lived process boundary used only while discovering skills.
+ *
+ * `probe()` always ends stdin, escalates to SIGKILL when needed, and awaits
+ * `exited`; implementations must make `exited` settle once the child is reaped.
+ */
+export interface SkillProbeProcess {
+  readonly stdin: SkillProbeStdin;
+  readonly stdout: ReadableStream<Uint8Array>;
+  readonly exited: Promise<number>;
+  kill(signal: "SIGKILL"): void;
+}
+
+/** Creates a short-lived discovery process in the supplied child cwd. */
+export interface SkillProbeProcessFactory {
+  create(cwd: string): SkillProbeProcess;
+}
+
+/** Injectable timings for a short-lived skill discovery process. */
+export interface SkillProbeTimings {
+  readonly responseTimeoutMs?: number;
+  readonly cleanupGraceMs?: number;
+}
+
+/** The fixed process configuration used by pi's short-lived discovery adapter. */
+export interface SkillProbeSpawnOptions {
+  readonly cmd: readonly string[];
+  readonly cwd: string;
+  readonly stdin: "pipe";
+  readonly stdout: "pipe";
+  readonly stderr: "ignore";
+}
+
+/**
+ * Parses pi's successful `get_commands` response into pi-compatible skill names.
+ *
+ * Rejects malformed skill entries instead of claiming a restriction was enforced.
+ */
+export function parseSkillCommands(response: unknown): readonly DiscoveredSkill[] {
+  if (!isRecord(response) || response.type !== "response" || response.command !== "get_commands") {
+    throw new Error("malformed get_commands response");
+  }
+  if (
+    response.success !== true ||
+    !isRecord(response.data) ||
+    !Array.isArray(response.data.commands)
+  ) {
+    throw new Error("get_commands did not return commands");
+  }
+  const discovered: DiscoveredSkill[] = [];
+  const names = new Set<string>();
+  for (const command of response.data.commands) {
+    if (!isRecord(command) || typeof command.source !== "string") {
+      throw new Error("malformed get_commands command");
+    }
+    if (command.source !== "skill") continue;
+    if (typeof command.name !== "string" || !command.name.startsWith("skill:")) {
+      throw new Error("malformed skill command name");
+    }
+    if (!isRecord(command.sourceInfo) || typeof command.sourceInfo.path !== "string") {
+      throw new Error(`skill command "${command.name}" has no sourceInfo.path`);
+    }
+    if (typeof command.sourceInfo.source !== "string") {
+      throw new Error(`skill command "${command.name}" has no sourceInfo.source`);
+    }
+    const name = command.name.slice("skill:".length);
+    if (name === "") throw new Error("malformed skill command name");
+    if (names.has(name)) continue;
+    names.add(name);
+    discovered.push({
+      name,
+      path: command.sourceInfo.path,
+      extensionInjected: command.sourceInfo.source.startsWith("extension:"),
+    });
+  }
+  return discovered;
+}
+
+const RESPONSE_TIMEOUT_MS = 30_000;
+const CLEANUP_GRACE_MS = 100;
+
+/** Wraps a process constructor as the narrow discovery-process factory seam. */
+export function createSkillProbeProcessFactory(
+  create: (cwd: string) => SkillProbeProcess,
+): SkillProbeProcessFactory {
+  return { create };
+}
+
+/**
+ * Adapts a pi process spawner to the discovery-process seam.
+ *
+ * It always starts `pi --mode rpc --no-session` with piped stdin/stdout so a
+ * probe is isolated from an Agent's long-lived transport.
+ */
+export function createBunSkillProbeProcessFactory(
+  spawn: (options: SkillProbeSpawnOptions) => SkillProbeProcess,
+): SkillProbeProcessFactory {
+  return createSkillProbeProcessFactory((cwd) =>
+    spawn({
+      cmd: ["pi", "--mode", "rpc", "--no-session"],
+      cwd,
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "ignore",
+    }),
+  );
+}
+
+/**
+ * Creates a short-lived pi skill discovery probe.
+ *
+ * Rejects when pi exits, emits malformed output, or misses the response timeout.
+ * Every outcome ends stdin, escalates to SIGKILL after the cleanup grace period,
+ * and waits for process reaping before this method settles.
+ */
+export function createSkillProbe(
+  processFactory: SkillProbeProcessFactory,
+  timings: SkillProbeTimings = {},
+): SkillProbeFactory {
+  const responseTimeoutMs = timings.responseTimeoutMs ?? RESPONSE_TIMEOUT_MS;
+  const cleanupGraceMs = timings.cleanupGraceMs ?? CLEANUP_GRACE_MS;
+  return {
+    async probe(cwd: string): Promise<readonly DiscoveredSkill[]> {
+      const process = processFactory.create(cwd);
+      try {
+        const id = "yaag-skill-probe-0";
+        process.stdin.write(`${JSON.stringify({ type: "get_commands", id })}\n`);
+        process.stdin.flush();
+        return await awaitResponse(process.stdout, process.exited, id, responseTimeoutMs);
+      } finally {
+        await cleanupProcess(process, cleanupGraceMs);
+      }
+    },
+  };
+}
+
+/** The production skill probe, backed by Bun's short-lived pi process. */
+export const liveSkillProbe = createSkillProbe(
+  createBunSkillProbeProcessFactory((options) => Bun.spawn({ ...options, cmd: [...options.cmd] })),
+);
+
+async function cleanupProcess(process: SkillProbeProcess, graceMs: number): Promise<void> {
+  process.stdin.end();
+  if (!(await exitsWithin(process.exited, graceMs))) process.kill("SIGKILL");
+  await process.exited;
+}
+
+async function exitsWithin(exited: Promise<number>, timeoutMs: number): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      exited.then(() => true),
+      new Promise<boolean>((resolve) => {
+        timer = setTimeout(() => resolve(false), timeoutMs);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function awaitResponse(
+  stdout: ReadableStream<Uint8Array>,
+  exited: Promise<number>,
+  id: string,
+  timeoutMs: number,
+): Promise<readonly DiscoveredSkill[]> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      readResponse(stdout, id),
+      exited.then(() => {
+        throw new Error("pi exited before answering get_commands");
+      }),
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error("pi did not answer get_commands")), timeoutMs);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function readResponse(
+  stdout: ReadableStream<Uint8Array>,
+  id: string,
+): Promise<readonly DiscoveredSkill[]> {
+  for await (const line of lines(stdout)) {
+    const frame = parseJson(line);
+    if (!isRecord(frame) || frame.type !== "response" || frame.id !== id) continue;
+    return parseSkillCommands(frame);
+  }
+  throw new Error("pi exited before answering get_commands");
+}
+
+async function* lines(stream: ReadableStream<Uint8Array>): AsyncGenerator<string> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let pending = "";
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      pending += decoder.decode(value, { stream: !done });
+      let newline = pending.indexOf("\n");
+      while (newline !== -1) {
+        yield pending.slice(0, newline);
+        pending = pending.slice(newline + 1);
+        newline = pending.indexOf("\n");
+      }
+      if (done) return;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function parseJson(line: string): unknown {
+  try {
+    return JSON.parse(line);
+  } catch {
+    throw new Error("pi emitted malformed JSON while discovering skills");
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/skill-restriction-transport.ts

@@ -0,0 +1,76 @@
+import type { DiscoveredSkill, SkillProbeFactory } from "./skill-probe.ts";
+import type {
+  AgentTransport,
+  OpenOptions,
+  TransportFactory,
+  TransportStartupObserver,
+} from "./transport.ts";
+
+/**
+ * Restricts live Agent skills by resolving pi's enabled names before startup.
+ *
+ * The cache belongs to one Run: concurrent requests for one cwd share its probe.
+ */
+export function skillRestrictionTransport(
+  inner: TransportFactory,
+  probe: SkillProbeFactory,
+): TransportFactory {
+  const discoveries = new Map<string, Promise<readonly DiscoveredSkill[]>>();
+  return {
+    async open(
+      options: OpenOptions,
+      observeStartup?: TransportStartupObserver,
+    ): Promise<AgentTransport> {
+      if (options.skills === undefined) {
+        if (options.inherit !== true) return inner.open(options, observeStartup);
+        if (options.disallowedSkills === undefined) return inner.open(options, observeStartup);
+      }
+      if (options.skills?.length === 0) {
+        return inner.open({ ...options, resolvedSkillPaths: [] }, observeStartup);
+      }
+      const discovered = await cachedDiscovery(discoveries, probe, options.cwd);
+      const resolvedSkillPaths = restrict(discovered, options.skills, options.disallowedSkills);
+      return inner.open({ ...options, resolvedSkillPaths }, observeStartup);
+    },
+  };
+}
+
+function cachedDiscovery(
+  discoveries: Map<string, Promise<readonly DiscoveredSkill[]>>,
+  probe: SkillProbeFactory,
+  cwd: string,
+): Promise<readonly DiscoveredSkill[]> {
+  const cached = discoveries.get(cwd);
+  if (cached) return cached;
+  const pending = probe.probe(cwd);
+  discoveries.set(cwd, pending);
+  return pending;
+}
+
+function restrict(
+  discovered: readonly DiscoveredSkill[],
+  allowlist: readonly string[] | undefined,
+  denylist: readonly string[] | undefined,
+): readonly string[] {
+  const byName = new Map<string, DiscoveredSkill>();
+  for (const skill of discovered) {
+    if (!byName.has(skill.name)) byName.set(skill.name, skill);
+  }
+  const unknown = [...(allowlist ?? []), ...(denylist ?? [])].filter((name) => !byName.has(name));
+  if (unknown.length > 0) throw new Error(`unknown skills: ${[...new Set(unknown)].join(", ")}`);
+  const undeniable = (denylist ?? []).filter((name) => byName.get(name)?.extensionInjected);
+  if (undeniable.length > 0) {
+    throw new Error(
+      `cannot deny extension-runtime-injected skills: ${[...new Set(undeniable)].join(", ")}`,
+    );
+  }
+  const denied = new Set(denylist);
+  const surviving = allowlist === undefined ? discovered.map((skill) => skill.name) : allowlist;
+  return surviving
+    .filter((name) => !denied.has(name))
+    .map((name) => {
+      const skill = byName.get(name);
+      if (!skill) throw new Error(`unknown skill: ${name}`);
+      return skill.path;
+    });
+}

package/src/spawn.ts

@@ -0,0 +1,241 @@
+import { resolve } from "node:path";
+import { Agent } from "./agent.ts";
+import { uniqueAgentName } from "./agent-names.ts";
+import { type AgentDefinition, agentDefinitionConfig, isAgentDefinition } from "./define-agent.ts";
+import { YaagError } from "./errors.ts";
+import type { EventSink } from "./events.ts";
+import { resolveExtensionPaths } from "./extension-paths.ts";
+import type { RunContext } from "./run-context.ts";
+import type { AgentTransport, TransportFactory, TransportStartup } from "./transport.ts";
+import type { AskOptions, Handle, SpawnOptions, SpawnOverrides } from "./types.ts";
+
+/** Dependencies for one Run's Agent-spawn gate. */
+export interface SpawnDependencies {
+  readonly factory: TransportFactory;
+  readonly agents: Agent[];
+  readonly emit: EventSink;
+  readonly sessionDir: string | undefined;
+  readonly programFile: string | undefined;
+}
+
+/** A RunContext spawn function that can synchronously stop accepting new Agents. */
+export interface SpawnGate {
+  readonly spawn: RunContext["spawn"];
+  close(): void;
+}
+
+/**
+ * Builds the Run-scoped Agent spawn gate.
+ *
+ * Allocates unique names within one Run and rejects with RUN_CLOSED once closed.
+ * Successfully opened Agents are registered immediately so Run cleanup reaps them.
+ */
+export function makeSpawn(deps: SpawnDependencies): SpawnGate {
+  const taken = new Set<string>();
+  let closed = false;
+  const spawn: RunContext["spawn"] = async (
+    definitionOrOptions: SpawnOptions | AgentDefinition = {},
+    overrides?: SpawnOverrides,
+  ): Promise<Handle> => {
+    if (closed) throw new YaagError("RUN_CLOSED", "run has already settled");
+    const request = resolveRequest(definitionOrOptions, overrides);
+    const cwd = resolve(request.spawnOptions.cwd ?? process.cwd());
+    const name = uniqueAgentName(request.spawnOptions.name, deps.agents.length, taken);
+    try {
+      const opened = await openTransport({
+        factory: deps.factory,
+        name,
+        cwd,
+        spawnOptions: request.spawnOptions,
+        sessionDir: deps.sessionDir,
+        programFile: deps.programFile,
+      });
+      const resolvedCwd = opened.startup.worktree?.cwd ?? cwd;
+      const branch = opened.startup.worktree?.branch;
+      const sessionFile = opened.startup.sessionFile;
+      const agent = new Agent({
+        name,
+        cwd: resolvedCwd,
+        branch,
+        transport: opened.transport,
+        emit: deps.emit,
+        spawnOptions: request.spawnOptions,
+        ...(request.askDefaults === undefined ? {} : { askDefaults: request.askDefaults }),
+        ...(request.definitionName === undefined ? {} : { definitionName: request.definitionName }),
+      });
+      deps.agents.push(agent);
+      deps.emit({
+        type: "agent_spawn",
+        agent: name,
+        model: agent.model,
+        cwd: resolvedCwd,
+        ...(branch === undefined ? {} : { branch }),
+        ...(sessionFile === undefined ? {} : { sessionFile }),
+      });
+      return agent;
+    } catch (error) {
+      if (request.definitionName !== undefined && isSpawnFailure(error)) {
+        throw new YaagError(
+          "SPAWN_FAILED",
+          `definition "${request.definitionName}": ${error.message}`,
+          name,
+        );
+      }
+      throw error;
+    }
+  };
+  return {
+    spawn,
+    close: (): void => {
+      closed = true;
+    },
+  };
+}
+
+type MutableSpawnOverrides = { -readonly [Key in keyof SpawnOverrides]: SpawnOverrides[Key] };
+
+interface SpawnRequest {
+  readonly spawnOptions: SpawnOptions;
+  readonly askDefaults: AskOptions | undefined;
+  /** Definition identity stays separate from a topology-overridden Agent name. */
+  readonly definitionName: string | undefined;
+}
+
+function resolveRequest(
+  definitionOrOptions: SpawnOptions | AgentDefinition,
+  overrides: SpawnOverrides | undefined,
+): SpawnRequest {
+  if (!isAgentDefinition(definitionOrOptions)) {
+    return { spawnOptions: definitionOrOptions, askDefaults: undefined, definitionName: undefined };
+  }
+  const topology = validateOverrides(overrides);
+  const config = agentDefinitionConfig(definitionOrOptions);
+  return {
+    spawnOptions: {
+      name: topology.name ?? config.name,
+      ...(topology.cwd === undefined ? {} : { cwd: topology.cwd }),
+      ...(topology.worktree === undefined ? {} : { worktree: topology.worktree }),
+      ...(config.model === undefined ? {} : { model: config.model }),
+      ...(config.thinking === undefined ? {} : { thinking: config.thinking }),
+      ...(config.tools === undefined ? {} : { tools: config.tools }),
+      ...(config.disallowedTools === undefined ? {} : { disallowedTools: config.disallowedTools }),
+      ...(config.skills === undefined ? {} : { skills: config.skills }),
+      ...(config.disallowedSkills === undefined
+        ? {}
+        : { disallowedSkills: config.disallowedSkills }),
+      ...(config.prompt === undefined
+        ? {}
+        : config.overrideSystemPrompt === true
+          ? { systemPrompt: config.prompt }
+          : { appendSystemPrompt: config.prompt }),
+    },
+    askDefaults: config.askDefaults,
+    definitionName: config.name,
+  };
+}
+
+function validateOverrides(overrides: unknown): SpawnOverrides {
+  if (overrides === undefined) return {};
+  if (typeof overrides !== "object" || overrides === null || Array.isArray(overrides)) {
+    throw new TypeError(
+      "spawn overrides must be an object: definitions own policy and spawn overrides own topology",
+    );
+  }
+  for (const key of Object.keys(overrides)) {
+    if (key !== "name" && key !== "cwd" && key !== "worktree") {
+      throw new TypeError(
+        `spawn override "${key}" is not allowed: definitions own policy and spawn overrides own topology`,
+      );
+    }
+  }
+  const topology: MutableSpawnOverrides = {};
+  for (const [key, value] of Object.entries(overrides)) {
+    if (key === "name") {
+      if (value !== undefined && typeof value !== "string") {
+        throw new TypeError('spawn override "name" must be a string when present');
+      }
+      topology.name = value;
+    }
+    if (key === "cwd") {
+      if (value !== undefined && typeof value !== "string") {
+        throw new TypeError('spawn override "cwd" must be a string when present');
+      }
+      topology.cwd = value;
+    }
+    if (key === "worktree") {
+      if (value !== undefined && typeof value !== "boolean") {
+        throw new TypeError('spawn override "worktree" must be a boolean when present');
+      }
+      topology.worktree = value;
+    }
+  }
+  return topology;
+}
+
+function isSpawnFailure(error: unknown): error is YaagError {
+  return error instanceof YaagError && error.code === "SPAWN_FAILED";
+}
+
+interface OpenTransportOptions {
+  readonly factory: TransportFactory;
+  readonly name: string;
+  readonly cwd: string;
+  readonly spawnOptions: SpawnOptions;
+  readonly sessionDir: string | undefined;
+  readonly programFile: string | undefined;
+}
+
+interface OpenedTransport {
+  readonly transport: AgentTransport;
+  readonly startup: TransportStartup;
+}
+
+async function openTransport(options: OpenTransportOptions): Promise<OpenedTransport> {
+  const startup: TransportStartup = {};
+  try {
+    const resolvedExtensionPaths =
+      options.spawnOptions.extensions === undefined
+        ? undefined
+        : await resolveExtensionPaths(options.spawnOptions.extensions, {
+            ...(options.programFile === undefined ? {} : { programFile: options.programFile }),
+            projectRoot: options.cwd,
+          });
+    const transport = await options.factory.open(
+      {
+        cwd: options.cwd,
+        name: options.name,
+        ...(options.spawnOptions.model === undefined ? {} : { model: options.spawnOptions.model }),
+        ...(options.spawnOptions.systemPrompt === undefined
+          ? {}
+          : { systemPrompt: options.spawnOptions.systemPrompt }),
+        ...(options.spawnOptions.thinking === undefined
+          ? {}
+          : { thinking: options.spawnOptions.thinking }),
+        ...(options.spawnOptions.appendSystemPrompt === undefined
+          ? {}
+          : { appendSystemPrompt: options.spawnOptions.appendSystemPrompt }),
+        ...(options.spawnOptions.inherit === undefined
+          ? {}
+          : { inherit: options.spawnOptions.inherit }),
+        ...(options.spawnOptions.tools === undefined ? {} : { tools: options.spawnOptions.tools }),
+        ...(options.spawnOptions.disallowedTools === undefined
+          ? {}
+          : { disallowedTools: options.spawnOptions.disallowedTools }),
+        ...(options.spawnOptions.skills === undefined
+          ? {}
+          : { skills: options.spawnOptions.skills }),
+        ...(options.spawnOptions.disallowedSkills === undefined
+          ? {}
+          : { disallowedSkills: options.spawnOptions.disallowedSkills }),
+        ...(resolvedExtensionPaths === undefined ? {} : { resolvedExtensionPaths }),
+        ...(options.spawnOptions.worktree === true ? { worktree: true } : {}),
+        ...(options.sessionDir === undefined ? {} : { sessionDir: options.sessionDir }),
+      },
+      (report) => Object.assign(startup, report),
+    );
+    return { transport, startup };
+  } catch (error) {
+    if (error instanceof YaagError) throw error;
+    throw new YaagError("SPAWN_FAILED", `agent "${options.name}": ${String(error)}`, options.name);
+  }
+}