@prismatic-io/lux 0.0.2-preview.3 → 0.0.2-preview.32

package/src/container/protocol.ts

@@ -0,0 +1,48 @@
+import type { Readable, Writable } from "node:stream";
+
+export type Message = {
+  id: number;
+  method?: string;
+  event?: string;
+  value?: unknown;
+  error?: string;
+  ack?: boolean;
+};
+export const writeMessage = (stream: Writable, message: Message): void => {
+  const line = JSON.stringify(message);
+  if (line.length > 8_000_000) throw new Error("container protocol message exceeds 8 MB");
+  stream.write(`${line}\n`);
+};
+export const readMessages = (
+  stream: Readable,
+  receive: (message: Message) => void,
+  fail: (error: Error) => void,
+): void => {
+  let buffer = "";
+  stream.setEncoding("utf8");
+  stream.on("data", (chunk: string) => {
+    try {
+      buffer += chunk;
+      for (;;) {
+        const newline = buffer.indexOf("\n");
+        if (newline < 0) break;
+        if (newline > 8_000_000) throw new Error("container protocol message exceeds 8 MB");
+        const message: unknown = JSON.parse(buffer.slice(0, newline));
+        buffer = buffer.slice(newline + 1);
+        if (
+          !message ||
+          typeof message !== "object" ||
+          !("id" in message) ||
+          !Number.isSafeInteger(message.id)
+        )
+          throw new Error("invalid container protocol message");
+        receive(message as Message);
+      }
+      if (buffer.length > 8_000_000) throw new Error("container protocol buffer exceeds 8 MB");
+    } catch (error) {
+      buffer = "";
+      stream.pause();
+      fail(error instanceof Error ? error : new Error(String(error)));
+    }
+  });
+};

package/src/container/resources.ts

@@ -0,0 +1,153 @@
+import { randomUUID } from "node:crypto";
+import { chmod, copyFile, lstat, mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import type { ContainerExecution } from "../core/driver-execution.js";
+import { exec } from "../core/exec.js";
+
+const mount = (source: string, target: string, readOnly = false): string => {
+  if ([source, target].some((path) => !isAbsolute(path) || /[,\r\n\0]/u.test(path)))
+    throw new Error(
+      "container mount paths must be absolute and contain no commas or control characters",
+    );
+  return `type=bind,source=${source},target=${target}${readOnly ? ",readonly" : ""}`;
+};
+
+export const prepareContainer = async (config: ContainerExecution, workspace: string) => {
+  const command = config.command ?? "docker";
+  const inspected = await exec(command, ["image", "inspect", "--format", "{{.Id}}", config.image], {
+    timeoutMs: config.startupTimeoutMs ?? 30_000,
+    maxBuffer: 4096,
+  });
+  if (inspected.exitCode !== 0 || !/^sha256:[a-f0-9]{64}$/u.test(inspected.stdout.trim()))
+    throw new Error(
+      "container image is unavailable; build or pull the configured image before running Lux",
+    );
+  const image = inspected.stdout.trim();
+  const home = await mkdtemp(join(tmpdir(), "lux-container-home-"));
+  const name = `lux-${randomUUID()}`;
+  const cleanup = async () => {
+    // Killing the Docker client does not stop the daemon-owned container.
+    const removed = await exec(command, ["rm", "--force", name], {
+      timeoutMs: 15_000,
+      maxBuffer: 4096,
+    });
+    if (removed.exitCode !== 0 && !removed.stderr.includes("No such container"))
+      throw new Error(
+        `failed to remove owned container '${name}'; private home retained at ${home}`,
+      );
+    await rm(home, { recursive: true, force: true });
+  };
+  try {
+    await chmod(home, 0o700);
+    for (const file of config.homeFiles ?? []) {
+      const target = join(home, file.destination);
+      await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+      if (file.source.kind === "file") {
+        if (!(await lstat(file.source.path)).isFile())
+          throw new Error("container home credential source must be a regular file");
+        await copyFile(file.source.path, target);
+      } else {
+        if (process.platform !== "darwin")
+          throw new Error("container Keychain credentials require macOS");
+        const result = await exec(
+          "/usr/bin/security",
+          ["find-generic-password", "-s", file.source.service, "-a", file.source.account, "-w"],
+          { timeoutMs: 10_000, maxBuffer: 1_000_000 },
+        );
+        if (result.exitCode !== 0 || result.stdoutTruncated)
+          throw new Error("could not read the explicitly configured container Keychain credential");
+        const value = result.stdout.trimEnd();
+        await writeFile(
+          target,
+          file.source.encoding === "go-keyring-base64" && value.startsWith("go-keyring-base64:")
+            ? Buffer.from(value.slice("go-keyring-base64:".length), "base64")
+            : value,
+          { mode: 0o600 },
+        );
+      }
+      await chmod(target, 0o600);
+    }
+    const root = await realpath(workspace);
+    const args = [
+      "run",
+      "--init",
+      "-i",
+      "--pull",
+      "never",
+      "--name",
+      name,
+      "--read-only",
+      "--cap-drop",
+      "ALL",
+      "--security-opt",
+      "no-new-privileges",
+      "--network",
+      config.network ?? "bridge",
+      "--memory",
+      config.memory ?? "4g",
+      "--cpus",
+      String(config.cpus ?? 2),
+      "--pids-limit",
+      String(config.pidsLimit ?? 512),
+      "--user",
+      config.user ?? `${process.getuid?.() ?? 1000}:${process.getgid?.() ?? 1000}`,
+      "--tmpfs",
+      "/tmp:rw,nosuid,nodev,exec,size=1g,mode=1777",
+      "--workdir",
+      root,
+      "--mount",
+      mount(root, root),
+      "--mount",
+      mount(await realpath(home), "/home/lux"),
+      "--env",
+      "HOME=/home/lux",
+      "--env",
+      "npm_config_yes=true",
+    ];
+    for (const entry of config.mounts ?? []) {
+      const source = await realpath(entry.source);
+      const target = resolve(entry.target ?? source);
+      if (
+        [
+          "/",
+          "/home",
+          "/home/lux",
+          "/tmp",
+          "/opt",
+          "/opt/lux",
+          "/usr",
+          "/bin",
+          "/etc",
+          "/proc",
+          "/sys",
+          "/dev",
+        ].some(
+          (reserved) =>
+            target === reserved || (reserved !== "/" && target.startsWith(`${reserved}/`)),
+        ) ||
+        target === root ||
+        root.startsWith(`${target}/`) ||
+        target.startsWith(`${root}/`)
+      )
+        throw new Error(
+          "additional container mounts must not overlap the workspace or runtime paths",
+        );
+      args.push("--mount", mount(source, target, entry.readOnly ?? true));
+    }
+    const env = { ...process.env };
+    for (const key of new Set([...(config.passEnv ?? []), ...Object.keys(config.env ?? {})])) {
+      if (["HOME", "NODE_OPTIONS", "NODE_PATH", "LD_PRELOAD", "LD_LIBRARY_PATH"].includes(key))
+        throw new Error(`reserved container environment variable '${key}'`);
+      const value = config.env?.[key] ?? process.env[key];
+      if (value === undefined) throw new Error(`container environment variable '${key}' is unset`);
+      env[key] = value;
+      args.push("--env", key);
+    }
+    args.push("--entrypoint", "node", image, config.worker ?? "/opt/lux/lib/container/worker.js");
+    return { command, args, env, image, root, cleanup };
+  } catch (error) {
+    await rm(home, { recursive: true, force: true });
+    throw error;
+  }
+};

package/src/container/worker.ts

@@ -0,0 +1,107 @@
+import { mkdir } from "node:fs/promises";
+import type { AgentDriver, DriverPlugin, StartContext } from "../core/driver.js";
+import { AnswerSchema } from "../core/events.js";
+import { buildRegistryFromConfig, LuxConfigSchema } from "../orchestrator/config.js";
+import { LUX_VERSION } from "../orchestrator/package-version.js";
+import { validatePluginConfig } from "../orchestrator/validate-plugin-config.js";
+import { type Message, readMessages, writeMessage } from "./protocol.js";
+
+let driver: AgentDriver | undefined;
+let eventId = 0;
+const acknowledgements = new Map<number, () => void>();
+const abort = new AbortController();
+const dispatch = async (message: Message): Promise<unknown> => {
+  if (message.method === "start") {
+    if (driver) throw new Error("container driver already started");
+    const request = message.value as {
+      version: string;
+      name: string;
+      module?: string;
+      config: unknown;
+      context: Omit<StartContext, "abortSignal">;
+    };
+    if (request.version !== LUX_VERSION)
+      throw new Error("container worker and host Lux versions differ; rebuild the image");
+    const plugin: DriverPlugin | undefined = request.module
+      ? (await import(request.module)).default
+      : buildRegistryFromConfig({
+          ...LuxConfigSchema.parse({}),
+          rootDir: process.cwd(),
+          configPath: null,
+        }).getDriver(request.name);
+    if (!plugin || plugin.name !== request.name)
+      throw new Error("container driver plugin is unavailable");
+    driver = await plugin.create(
+      validatePluginConfig(
+        plugin.configSchema,
+        request.config,
+        `container driver '${request.name}'`,
+      ),
+    );
+    for (const event of ["interrupt", "progress", "done", "error"] as const) {
+      driver.on(
+        event,
+        (value) =>
+          new Promise<void>((resolve) => {
+            const id = ++eventId;
+            acknowledgements.set(id, resolve);
+            writeMessage(process.stdout, { id, event, value });
+          }),
+      );
+    }
+    await mkdir("/tmp/lux-run", { recursive: true });
+    await mkdir("/tmp/lux-runs", { recursive: true });
+    return driver.start({
+      ...request.context,
+      isolatedHome: "/home/lux",
+      abortSignal: abort.signal,
+    });
+  }
+  if (!driver) throw new Error("container driver has not started");
+  switch (message.method) {
+    case "respond":
+      return driver.respond(AnswerSchema.parse(message.value));
+    case "quiesce":
+      return driver.quiesce?.();
+    case "collect":
+      return driver.collect();
+    case "close":
+      return driver.close();
+    default:
+      throw new Error("unknown container RPC method");
+  }
+};
+readMessages(
+  process.stdin,
+  (message) => {
+    if (message.ack) {
+      acknowledgements.get(message.id)?.();
+      acknowledgements.delete(message.id);
+      return;
+    }
+    void dispatch(message).then(
+      (value) => writeMessage(process.stdout, { id: message.id, value }),
+      (error: unknown) =>
+        writeMessage(process.stdout, {
+          id: message.id,
+          error: error instanceof Error ? error.message : String(error),
+        }),
+    );
+  },
+  () => {
+    abort.abort();
+    process.exitCode = 1;
+    process.stdin.destroy();
+  },
+);
+process.stdin.on("end", () => {
+  abort.abort();
+  for (const resolve of acknowledgements.values()) resolve();
+  void driver?.close().finally(() => {
+    process.exitCode = 0;
+  });
+});
+process.stdout.on("error", () => {
+  abort.abort();
+  process.exitCode = 1;
+});

package/src/core/action-events.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import type { RunEvent } from "./events.js";
+
+export const ActionCategorySchema = z.enum([
+  "query",
+  "mutation",
+  "durable-mutation",
+  "execution",
+  "interaction",
+]);
+export type ActionCategory = z.infer<typeof ActionCategorySchema>;
+
+export const ActionProgressPayloadSchema = z
+  .object({
+    name: z.string(),
+    category: ActionCategorySchema,
+  })
+  .strict();
+export type ActionProgressPayload = z.infer<typeof ActionProgressPayloadSchema>;
+
+export const ActionTimingSchema = z.object({
+  timeToFirstActionMs: z.exactOptional(z.number().nonnegative()),
+  timeToFirstMutationMs: z.exactOptional(z.number().nonnegative()),
+  timeToFirstDurableMutationMs: z.exactOptional(z.number().nonnegative()),
+});
+export type ActionTiming = z.infer<typeof ActionTimingSchema>;
+
+export const actionTiming = (events: readonly RunEvent[]): ActionTiming => {
+  const startEvent = events.find(
+    (event) => event.type === "lifecycle" && event.stage === "start-driver",
+  );
+  const startedAt = startEvent?.type === "lifecycle" ? startEvent.ts : undefined;
+  if (startedAt === undefined) return {};
+
+  const actions = events.flatMap((event) => {
+    if (event.type !== "progress" || event.kind !== "action") return [];
+    const payload = ActionProgressPayloadSchema.safeParse(event.payload).data;
+    return payload ? [{ ...payload, ts: event.ts }] : [];
+  });
+  const elapsed = (category: "any" | "mutation" | "durable-mutation") => {
+    const timestamps = actions.flatMap(({ category: candidate, ts }) => {
+      if (category === "any") return [ts];
+      if (category === "mutation") {
+        return candidate === "mutation" || candidate === "durable-mutation" ? [ts] : [];
+      }
+      return candidate === category ? [ts] : [];
+    });
+    return timestamps.length > 0 ? Math.max(0, Math.min(...timestamps) - startedAt) : undefined;
+  };
+
+  const timeToFirstActionMs = elapsed("any");
+  const timeToFirstMutationMs = elapsed("mutation");
+  const timeToFirstDurableMutationMs = elapsed("durable-mutation");
+  return {
+    ...(timeToFirstActionMs === undefined ? {} : { timeToFirstActionMs }),
+    ...(timeToFirstMutationMs === undefined ? {} : { timeToFirstMutationMs }),
+    ...(timeToFirstDurableMutationMs === undefined ? {} : { timeToFirstDurableMutationMs }),
+  };
+};

package/src/core/agent-activity.ts

@@ -0,0 +1,236 @@
+import { z } from "zod";
+import { ActionProgressPayloadSchema } from "./action-events.js";
+import { AgentCompletedPayloadSchema, AgentSpawnPayloadSchema } from "./agent-events.js";
+import type { AgentAttribution, ReadyState, RunEvent } from "./events.js";
+import { ToolCallPayloadSchema, ToolResultPayloadSchema } from "./tool-events.js";
+import { TokenUsageSchema } from "./usage.js";
+
+export const AgentActivitySchema = z.object({
+  agent: z.object({
+    id: z.string(),
+    role: z.enum(["main", "subagent"]),
+    parentId: z.exactOptional(z.string()),
+    spawnToolUseId: z.exactOptional(z.string()),
+    name: z.exactOptional(z.string()),
+    model: z.exactOptional(z.string()),
+  }),
+  startedAt: z.number(),
+  endedAt: z.number(),
+  durationMs: z.number().nonnegative(),
+  status: z.enum(["completed", "failed", "cancelled", "unknown"]),
+  eventCount: z.number().int().nonnegative(),
+  usage: TokenUsageSchema.extend({ total: z.number().int().nonnegative() }),
+  toolCalls: z.object({
+    total: z.number().int().nonnegative(),
+    succeeded: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+    unresolved: z.number().int().nonnegative(),
+  }),
+  actions: z.object({
+    total: z.number().int().nonnegative(),
+    mutations: z.number().int().nonnegative(),
+    durableMutations: z.number().int().nonnegative(),
+    timeToFirstActionMs: z.exactOptional(z.number().nonnegative()),
+    timeToFirstMutationMs: z.exactOptional(z.number().nonnegative()),
+    timeToFirstDurableMutationMs: z.exactOptional(z.number().nonnegative()),
+  }),
+});
+export type AgentActivity = z.infer<typeof AgentActivitySchema>;
+
+const legacyAttribution = (
+  event: Extract<RunEvent, { type: "progress" }>,
+  ready: ReadyState,
+): AgentAttribution => {
+  const payload = event.payload;
+  const parentToolUseId =
+    typeof payload === "object" && payload !== null && "parentToolUseId" in payload
+      ? payload.parentToolUseId
+      : undefined;
+  const spawnToolUseId =
+    typeof parentToolUseId === "string" && parentToolUseId.length > 0 ? parentToolUseId : undefined;
+  return spawnToolUseId
+    ? {
+        id: `subagent:${spawnToolUseId}`,
+        role: "subagent" as const,
+        parentId: ready.agentId,
+        spawnToolUseId,
+      }
+    : { id: ready.agentId, role: "main" as const, ...(ready.model ? { model: ready.model } : {}) };
+};
+
+type MutableActivity = AgentActivity & { calls: Map<string, "pending" | "succeeded" | "failed"> };
+type ProgressEvent = Extract<RunEvent, { type: "progress" }>;
+type SpawnInfo = { ts: number; name?: string; model?: string };
+
+const initialActivity = (agent: AgentAttribution, startedAt: number): MutableActivity => ({
+  agent,
+  startedAt,
+  endedAt: startedAt,
+  durationMs: 0,
+  status: "unknown",
+  eventCount: 0,
+  usage: { input: 0, output: 0, cacheRead: 0, cacheCreation: 0, total: 0 },
+  toolCalls: { total: 0, succeeded: 0, failed: 0, unresolved: 0 },
+  actions: { total: 0, mutations: 0, durableMutations: 0 },
+  calls: new Map(),
+});
+
+const collectSpawnInfo = (events: RunEvent[]): Map<string, SpawnInfo> => {
+  const spawns = new Map<string, SpawnInfo>();
+  for (const event of events) {
+    if (event.type !== "progress" || event.kind !== "tool-call") continue;
+    const call = ToolCallPayloadSchema.safeParse(event.payload).data;
+    if (!call) continue;
+    const input = z
+      .object({
+        name: z.string().min(1).optional(),
+        subagent_type: z.string().min(1).optional(),
+        agent: z.string().min(1).optional(),
+        role: z.string().min(1).optional(),
+        model: z.string().min(1).optional(),
+      })
+      .loose()
+      .safeParse(call.input).data;
+    const name = input?.name ?? input?.subagent_type ?? input?.agent ?? input?.role;
+    spawns.set(call.toolUseId, {
+      ts: event.ts,
+      ...(name ? { name } : {}),
+      ...(input?.model ? { model: input.model } : {}),
+    });
+  }
+  return spawns;
+};
+
+const applyLifecycle = (
+  event: ProgressEvent,
+  activities: Map<string, MutableActivity>,
+): boolean => {
+  if (event.kind === "agent-spawn") {
+    const spawn = AgentSpawnPayloadSchema.safeParse(event.payload).data;
+    if (spawn && !activities.has(spawn.agent.id)) {
+      activities.set(spawn.agent.id, initialActivity(spawn.agent, event.ts));
+    }
+    return true;
+  }
+  if (event.kind !== "agent-completed") return false;
+  const completed = AgentCompletedPayloadSchema.safeParse(event.payload).data;
+  const activity = completed ? activities.get(completed.agentId) : undefined;
+  if (activity && completed) {
+    activity.endedAt = Math.max(activity.endedAt, event.ts);
+    activity.durationMs = Math.max(0, activity.endedAt - activity.startedAt);
+    activity.status = completed.status;
+  }
+  return true;
+};
+
+const activityFor = (
+  event: ProgressEvent,
+  ready: ReadyState,
+  driverStartedAt: number,
+  spawns: Map<string, SpawnInfo>,
+  activities: Map<string, MutableActivity>,
+): MutableActivity => {
+  const agent = event.agent ?? legacyAttribution(event, ready);
+  const existing = activities.get(agent.id);
+  if (existing) return existing;
+  const spawn = agent.spawnToolUseId ? spawns.get(agent.spawnToolUseId) : undefined;
+  const name = agent.name ?? spawn?.name;
+  const model = agent.model ?? spawn?.model;
+  const attributedAgent = {
+    ...agent,
+    ...(name ? { name } : {}),
+    ...(model ? { model } : {}),
+  };
+  const startedAt =
+    agent.role === "subagent" && agent.spawnToolUseId
+      ? (spawn?.ts ?? event.ts)
+      : driverStartedAt || event.ts;
+  return activities.get(agent.id) ?? initialActivity(attributedAgent, startedAt);
+};
+
+const addAction = (event: ProgressEvent, activity: MutableActivity): void => {
+  const action = ActionProgressPayloadSchema.safeParse(event.payload).data;
+  if (!action) return;
+  const elapsed = Math.max(0, event.ts - activity.startedAt);
+  activity.actions.total++;
+  activity.actions.timeToFirstActionMs ??= elapsed;
+  if (action.category === "mutation" || action.category === "durable-mutation") {
+    activity.actions.mutations++;
+    activity.actions.timeToFirstMutationMs ??= elapsed;
+  }
+  if (action.category === "durable-mutation") {
+    activity.actions.durableMutations++;
+    activity.actions.timeToFirstDurableMutationMs ??= elapsed;
+  }
+};
+
+const addUsage = (event: ProgressEvent, activity: MutableActivity): void => {
+  const usage = TokenUsageSchema.safeParse(event.payload).data;
+  if (!usage) return;
+  activity.usage.input += usage.input;
+  activity.usage.output += usage.output;
+  activity.usage.cacheRead += usage.cacheRead;
+  activity.usage.cacheCreation += usage.cacheCreation;
+  activity.usage.total += usage.input + usage.output + usage.cacheRead + usage.cacheCreation;
+};
+
+const addWork = (event: ProgressEvent, activity: MutableActivity): void => {
+  activity.eventCount++;
+  activity.endedAt = Math.max(activity.endedAt, event.ts);
+  activity.durationMs = Math.max(0, activity.endedAt - activity.startedAt);
+  if (event.kind === "tool-call") {
+    const call = ToolCallPayloadSchema.safeParse(event.payload).data;
+    if (call && !activity.calls.has(call.toolUseId)) {
+      activity.calls.set(call.toolUseId, "pending");
+      activity.toolCalls.total++;
+    }
+    return;
+  }
+  if (event.kind === "tool-result") {
+    const result = ToolResultPayloadSchema.safeParse(event.payload).data;
+    if (result && activity.calls.has(result.toolUseId)) {
+      activity.calls.set(result.toolUseId, result.isError ? "failed" : "succeeded");
+    }
+    return;
+  }
+  if (event.kind === "action") addAction(event, activity);
+  if (event.kind === "usage") addUsage(event, activity);
+};
+
+export const summarizeAgentActivity = (events: RunEvent[], ready: ReadyState): AgentActivity[] => {
+  const driverStart = events.find(
+    (event): event is Extract<RunEvent, { type: "lifecycle" }> =>
+      event.type === "lifecycle" && event.stage === "start-driver",
+  );
+  const driverStartedAt = driverStart?.ts ?? 0;
+  const spawns = collectSpawnInfo(events);
+  const activities = new Map<string, MutableActivity>();
+  for (const event of events) {
+    if (event.type !== "progress") continue;
+    if (applyLifecycle(event, activities)) continue;
+    const activity = activityFor(event, ready, driverStartedAt, spawns, activities);
+    addWork(event, activity);
+    activities.set(activity.agent.id, activity);
+  }
+
+  if (!activities.has(ready.agentId)) {
+    activities.set(
+      ready.agentId,
+      initialActivity(
+        {
+          id: ready.agentId,
+          role: "main",
+          ...(ready.model ? { model: ready.model } : {}),
+        },
+        driverStartedAt,
+      ),
+    );
+  }
+  return [...activities.values()]
+    .map(({ calls, ...activity }) => {
+      for (const outcome of calls.values())
+        activity.toolCalls[outcome === "pending" ? "unresolved" : outcome]++;
+      return AgentActivitySchema.parse(activity);
+    })
+    .sort((a, b) => a.startedAt - b.startedAt || a.agent.id.localeCompare(b.agent.id));
+};

package/src/core/agent-environment.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+
+export const InheritEnvironmentSchema = z.union([z.array(z.string().min(1)), z.literal(true)]);
+export type InheritEnvironment = z.infer<typeof InheritEnvironmentSchema>;
+
+const nativeEnvironment = new Set([
+  "PATH",
+  "HOME",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "TMPDIR",
+  "TMP",
+  "TEMP",
+  "LANG",
+  "LANGUAGE",
+  "TERM",
+  "COLORTERM",
+  "NO_COLOR",
+  "FORCE_COLOR",
+  "CI",
+  "TZ",
+  "XDG_CONFIG_HOME",
+  "XDG_DATA_HOME",
+  "XDG_CACHE_HOME",
+  "XDG_STATE_HOME",
+  "CODEX_HOME",
+  "CLAUDE_CONFIG_DIR",
+  "CLAUDE_SECURESTORAGE_CONFIG_DIR",
+  "GROK_HOME",
+  "SYSTEMROOT",
+  "WINDIR",
+  "COMSPEC",
+  "PATHEXT",
+  "APPDATA",
+  "LOCALAPPDATA",
+  "USERPROFILE",
+  "HOMEDRIVE",
+  "HOMEPATH",
+  "USERNAME",
+]);
+
+export const agentEnvironment = (
+  parent: NodeJS.ProcessEnv,
+  inherit: InheritEnvironment = true,
+  overrides?: NodeJS.ProcessEnv,
+): Record<string, string> => {
+  const selected =
+    inherit === true
+      ? { ...parent }
+      : Object.fromEntries(
+          Object.entries(parent).filter(
+            ([name]) =>
+              nativeEnvironment.has(name.toUpperCase()) ||
+              name.startsWith("LC_") ||
+              inherit.includes(name),
+          ),
+        );
+  return Object.fromEntries(
+    Object.entries({ ...selected, ...overrides }).filter(
+      (entry): entry is [string, string] => entry[1] !== undefined,
+    ),
+  );
+};

package/src/core/agent-events.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { AgentAttributionSchema } from "./events.js";
+
+export const AGENT_SPAWN_KIND = "agent-spawn" as const;
+export const AGENT_COMPLETED_KIND = "agent-completed" as const;
+
+export const AgentSpawnPayloadSchema = z.object({
+  agent: AgentAttributionSchema.extend({ role: z.literal("subagent") }),
+  prompt: z.exactOptional(z.string()),
+});
+export type AgentSpawnPayload = z.infer<typeof AgentSpawnPayloadSchema>;
+
+export const AgentCompletedPayloadSchema = z.object({
+  agentId: z.string().min(1),
+  status: z.enum(["completed", "failed", "cancelled", "unknown"]),
+});
+export type AgentCompletedPayload = z.infer<typeof AgentCompletedPayloadSchema>;