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

package/src/core/run.ts

@@ -1,6 +1,10 @@
 import { z } from "zod";
+import { ActionTimingSchema } from "./action-events.js";
+import { AgentActivitySchema } from "./agent-activity.js";
 import { EvalCaseSchema } from "./case.js";
 import { ArtifactSchema } from "./driver.js";
+import { DriverMetricsSchema } from "./driver-metrics.js";
+import { EnvironmentDeclarationSchema } from "./environment.js";
 import { ErrorEventReasonSchema, ReadyStateSchema, RunEventSchema } from "./events.js";
 import { ToolOutcomeSummarySchema } from "./tool-events.js";
 import { RunUsageSchema } from "./usage.js";
@@ -24,7 +28,24 @@ export const RunProvenanceSchema = z.object({
     arch: z.string(),
     node: z.string(),
     bun: z.exactOptional(z.string()),
+    host: z.exactOptional(
+      z.object({
+        osRelease: z.string(),
+        cpuModels: z.array(z.string()),
+        logicalCpuCount: z.number().int().nonnegative(),
+        availableParallelism: z.number().int().positive(),
+        totalMemoryBytes: z.number().int().nonnegative(),
+      }),
+    ),
   }),
+  environment: z.exactOptional(
+    z.object({
+      /** Declared by the author, not independently verified or enforced by Lux. */
+      declared: z.exactOptional(EnvironmentDeclarationSchema),
+      /** Effective Lux worker limit for this run's suite; direct runs use one. */
+      concurrency: z.number().int().positive(),
+    }),
+  ),
   source: z.exactOptional(
     z.object({
       /** Case path relative to its repository root, when one was found. */
@@ -49,6 +70,8 @@ export const RunProvenanceSchema = z.object({
   fixturesHash: z.exactOptional(z.string()),
   subjectHash: z.exactOptional(z.string()),
   profileId: z.exactOptional(z.string()),
+  /** Harness matrix permutation (`driver:model:effort`) this run was filed under. */
+  permutationId: z.exactOptional(z.string()),
   experimentId: z.exactOptional(z.string()),
   variantId: z.exactOptional(z.string()),
   candidateId: z.exactOptional(z.string()),
@@ -103,6 +126,8 @@ export const RunMetadataSchema = z.object({
    * eval overhead.
    */
   usage: RunUsageSchema,
+  /** Absent in older records; zero alone did not establish availability. */
+  agentUsageAvailability: z.exactOptional(z.enum(["reported", "unavailable"])),
   modelAccounting: z.exactOptional(
     z.object({
       agentCalls: z.number().int().nonnegative(),
@@ -112,6 +137,8 @@ export const RunMetadataSchema = z.object({
     }),
   ),
   cost: z.exactOptional(z.object({ usd: z.exactOptional(z.number()) })),
+  /** Driver-defined scalar measurements with display and optimization semantics. */
+  driverMetrics: z.exactOptional(DriverMetricsSchema),
   interruptCounts: z.object({ ask: z.number(), approve: z.number(), custom: z.number() }),
   /** Legacy raw count of progress events whose kind is `tool-call`. */
   toolCallCount: z.exactOptional(z.number()),
@@ -124,6 +151,10 @@ export const RunMetadataSchema = z.object({
   ),
   /** Wall-clock per phase, derived from the lifecycle event stream. */
   phaseDurationMs: z.exactOptional(PhaseDurationsSchema),
+  /** Driver-reported semantic action latency, measured from `start-driver`. */
+  actionTiming: z.exactOptional(ActionTimingSchema),
+  /** Per-agent lifecycle and activity derived from the attributed event stream. */
+  agentActivity: z.exactOptional(z.array(AgentActivitySchema)),
   /**
    * Harness/infrastructure failure that invalidates this run as candidate
    * evidence. A driver-reported subject failure intentionally leaves this

package/src/core/usage.ts

@@ -121,3 +121,11 @@ export const parseAgentUsage = (raw: unknown): TokenUsage | null => {
   if (!AGENT_USAGE_KEYS.some((key) => key in raw)) return null;
   return AgentUsageSchema.safeParse(raw).data ?? null;
 };
+
+/** Legacy nonzero counts remain usable; legacy zero counts are unknown. */
+export const hasAgentUsage = (metadata: {
+  usage: RunUsage;
+  agentUsageAvailability?: "reported" | "unavailable";
+}): boolean =>
+  metadata.agentUsageAvailability === "reported" ||
+  (metadata.agentUsageAvailability === undefined && !isUsageEmpty(metadata.usage.agent));

package/src/core/wire.ts

@@ -47,6 +47,7 @@ const ErrorEventSchema = z.object({
   type: z.literal("error"),
   exitReason: ErrorEventReasonSchema.default("error"),
   reason: z.string(),
+  summary: z.unknown().optional(),
 });
 
 export const WireEventSchema = z.discriminatedUnion("type", [
@@ -85,7 +86,10 @@ const wireEventToParsed = (event: WireEvent): ParsedDriverEvent => {
   if (event.type === "done") {
     return { tag: "done", done: { exitReason: "done", summary: event.summary } };
   }
-  return { tag: "error", error: { exitReason: event.exitReason, reason: event.reason } };
+  return {
+    tag: "error",
+    error: { exitReason: event.exitReason, reason: event.reason, summary: event.summary },
+  };
 };
 
 /**

package/src/drivers/antigravity/README.md

@@ -0,0 +1,171 @@
+# Antigravity driver
+
+The `antigravity` driver runs Google Antigravity CLI (`agy`) in its headless
+streaming mode: `agy --input-format stream-json --output-format stream-json`.
+Install the CLI and sign in before Lux starts it; headless runs fail with
+`authentication required` when no cached credential exists.
+
+```ts
+{
+  name: "antigravity",
+  config: {
+    model: "YOUR_ANTIGRAVITY_MODEL",
+    reasoningEffort: "low",
+  },
+}
+```
+
+`model` is required and Lux never inherits the CLI default. Use a base slug
+such as `gemini-3.8-flash`; `reasoningEffort` takes Antigravity's own `low`,
+`medium`, or `high` and selects that variant through `--effort`. The harness
+catalog in `core/harness-catalogs/antigravity.ts` lists which levels each model
+offers (Gemini Flash has three, Gemini 3.1 Pro has `low` and `high`, Claude and
+GPT-OSS have none), and an effort outside that list is rejected before the CLI
+starts. When no effort is set, a model with levels runs at `low`.
+
+Lux writes one `user` event with the case prompt, closes stdin, and reads
+`init`, `step_update`, and `result` events. Tool steps become paired
+`tool-call` and `tool-result` events keyed by step index, response deltas become
+`agent-message` progress, other steps stay visible as `antigravity-step`
+progress, and the final `result` usage is recorded as agent usage. The terminal
+response is also retained as message evidence when it was not already streamed.
+Both `DONE` and `ERROR` tool steps close the corresponding tool call; failed
+steps retain their error message. A result with `denied_actions` is an error even
+when Antigravity reports `SUCCESS`. `WAITING` and other non-success statuses are
+also errors. Configure the required scoped permissions for the
+headless evaluation; Lux does not retry a denial with broader permissions.
+
+Lux explicitly selects `mode: "accept-edits"` for coding tasks. Set `mode: "plan"`
+for planning runs. On Antigravity 1.2.10, omitting `--mode` can leave terminal
+workspaces read-only even when native file tools can edit them and scoped write
+grants exist. `accept-edits` permits workspace writes within the terminal sandbox;
+it does not disable that sandbox or authorize outside-sandbox execution.
+
+## Run-scoped configuration
+
+Lux can own the CLI settings for a run:
+
+```ts
+{
+  name: "antigravity",
+  config: {
+    model: "gemini-3.1-pro",
+    reasoningEffort: "low",
+    sandbox: true,
+    permissionMode: "proceed-in-sandbox",
+    permissions: { allow: ["read_url(registry.npmjs.org)"] },
+  },
+}
+```
+
+This mode gives only the child process a private home directory. Lux writes
+`enableTerminalSandbox: true`, `toolPermission: "proceed-in-sandbox"`, and the
+configured `permissions` there. It does not edit the user's settings, copy their
+history/plugins, or reuse their project records. Concurrent runs get distinct
+homes. `permissionMode: "inherit"` is the default and preserves the previous
+behavior. Scoped mode requires `sandbox: true`, rejects `skipPermissions: true`
+and a host `project`, and supports scoped `allow`, `deny`, and `ask` lists.
+
+Authentication must work in that private home. An inherited `GEMINI_API_KEY` is
+passed to the CLI. For file-based OAuth, Lux copies only the CLI's
+`antigravity-oauth-token` into the private runtime, using the normal CLI token
+path by default or an explicit `authTokenFile`. The copy has mode 0600 inside
+a mode-0700 runtime directory; token refresh cannot modify the source file.
+On macOS, `reuseKeychain: true` explicitly opts into reading Antigravity’s own
+Keychain entry (service `gemini`, account `antigravity`) when the default token
+file is absent. Lux writes that credential only to the private runtime and
+removes it on close. This option defaults to false. Do not put secret values in
+committed Lux configuration.
+
+Before deleting a private runtime, Lux snapshots native deliverables from its
+`brain` directory under `antigravity-artifacts/` in the task artifacts. This keeps
+handoff documents available to graders even when the final response only links
+to them. Hidden CLI logs, revision copies, metadata, and symlinks are excluded;
+collection fails explicitly above 500 files or 32 MiB. Existing user-home brain
+history is never scanned in inherited mode.
+
+The runtime is outside task artifacts and removed on driver close, collection,
+and startup failure. A force-killed Lux process cannot run cleanup; private
+runtime directories have the `lux-antigravity-home-` prefix in the OS temp root.
+This is configuration separation, not a complete OS security boundary; the
+driver continues declaring `isolation: false`.
+
+Grant scoped file and documentation access as needed, including read access to
+language runtimes installed outside system directories. `command(...)` allow
+rules can authorize outside-sandbox execution too. Keep them absent when that
+execution must remain unapproved; `unsandboxed(...)` rules were ignored in the
+observed macOS CLI. The terminal sandbox and native file-tool permissions are
+separate. Extra CLI arguments remain caller-controlled.
+
+Each run creates a fresh Antigravity project and passes its canonical working
+directory through `--add-dir` and an explicit task-workspace prompt preamble.
+Set `project` to reuse an explicitly configured
+project, and `addDirs` for additional reference directories. Process cwd alone
+does not select an Antigravity project. Project selection does not grant tool
+permissions: Antigravity 1.2.10 can still deny workspace writes in headless mode.
+`skipPermissions` remains false by default and must be explicitly enabled to
+bypass tool permission checks.
+
+The headless protocol carries no user questions or permission prompts, so the
+driver is not interactive. In inherited mode, Antigravity still reads user
+settings and conversation history. Controlled experiments are not
+declared.
+
+Regression tests cover the `ERROR` tool step followed by `SUCCESS` with denied
+actions observed in an authenticated Antigravity 1.2.10 session.
+
+## Live readiness checks
+
+From a Lux checkout, after installing locked dependencies and authenticating `agy`:
+
+```sh
+LUX_ANTIGRAVITY_MODEL=gemini-3.1-pro mise run smoke:antigravity
+```
+
+This opt-in smoke test consumes model usage. It runs four bounded checks in
+fresh artifact workspaces: a tool-free protocol response, a Node write/read
+check, native handoff-document capture, and a local HTTP server/client check. It stops on the first failure and
+retains events, fixtures, and results under `.lux-runs/antigravity-smoke/`.
+After building, select one stage with
+`LUX_ANTIGRAVITY_MODEL=gemini-3.1-pro node scripts/smoke-antigravity.mjs protocol`
+(or `workspace` / `artifact` / `loopback`); `--list` makes no model calls.
+
+The script uses `permissionMode: "proceed-in-sandbox"` with scoped read access to
+the running Node installation, plus localhost grants for the loopback stage.
+It never changes global settings. Authenticate
+with an inherited `GEMINI_API_KEY`, a normal CLI OAuth token file, or
+`LUX_ANTIGRAVITY_AUTH_TOKEN_FILE` pointing to such a file. To opt into macOS
+Keychain reuse, set `LUX_ANTIGRAVITY_REUSE_KEYCHAIN=1`. On macOS with CLI 1.2.12,
+private-runtime authentication and sandboxed file writes passed on 2026-09-29.
+The loopback check failed with `connect EPERM 127.0.0.1`; its missing fixture
+evidence correctly failed the smoke test despite normal agent completion.
+
+`--sandbox` alone does not select an execution policy: a native 1.2.12 probe on
+macOS with only `enableTerminalSandbox: true` denied the command, then returned
+`SUCCESS` with empty text and `denied_actions`. Lux correctly classifies that
+result as an error. A separate tool-free live probe passed in inherited mode;
+it does not establish private-runtime authentication.
+
+A passing protocol check establishes authentication and streaming only.
+Workspace and loopback checks require fixture-produced evidence; a completed
+agent response alone cannot pass them. These checks do not establish skill
+quality, package-install access, or complete sandbox isolation. Scoped access
+to a runtime outside system directories may also be necessary.
+
+On macOS, native 1.2.11 probes could write/build in editing mode but could
+not connect to their own loopback HTTP server: direct connections returned
+`EPERM`, and proxy requests rejected literal IPs or nonstandard HTTP ports.
+That failure occurred without Lux. Recheck the installed CLI with `loopback`
+before running suites that depend on local HTTP fixtures. Domain grants alone
+have not been shown to resolve this restriction. Keep a native reproduction
+separate from driver traces when diagnosing it; do not treat it as skill failure
+or bypass the sandbox to obtain a passing score.
+
+Protocol references:
+
+- [Antigravity CLI headless mode](https://antigravity.google/docs/cli/headless/)
+- [Antigravity CLI](https://github.com/google-antigravity/antigravity-cli)
+
+- [Antigravity terminal sandbox](https://antigravity.google/docs/sandbox?tab=cli)
+- [CLI settings reference](https://antigravity.google/docs/cli/reference/)
+- [Native artifacts](https://antigravity.google/docs/cli/artifacts/)

package/src/drivers/antigravity/artifacts.ts

@@ -0,0 +1,37 @@
+import { readFile, realpath } from "node:fs/promises";
+import { join, sep } from "node:path";
+import { writeArtifactSnapshot } from "../../core/artifact-snapshot.js";
+import { walkArtifacts } from "../shared/artifacts.js";
+
+export const captureAntigravityArtifacts = async (
+  home: string,
+  destination: string,
+): Promise<void> => {
+  const brain = join(home, ".gemini/antigravity-cli/brain");
+  let root: string;
+  try {
+    root = await realpath(brain);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  if (!root.startsWith(`${await realpath(home)}${sep}`))
+    throw new Error("Antigravity artifact directory escaped its private runtime");
+  // Native revisions and CLI bookkeeping are not authored deliverables.
+  const artifacts = (await walkArtifacts(brain)).filter(
+    ({ path }) => !/\.(?:metadata\.json|resolved(?:\.\d+)?)$/.test(path),
+  );
+  if (!artifacts.length) return;
+  const maxBytes = 32 * 1024 * 1024;
+  if (artifacts.reduce((total, artifact) => total + (artifact.size ?? 0), 0) > maxBytes)
+    throw new Error("Antigravity native artifacts exceed the 32 MiB collection limit");
+  const files = Object.fromEntries(
+    await Promise.all(artifacts.map(async ({ path }) => [path, await readFile(join(brain, path))])),
+  );
+  await writeArtifactSnapshot({
+    artifactsDir: destination,
+    name: "antigravity-artifacts",
+    files,
+    maxBytes,
+  });
+};

package/src/drivers/antigravity/config.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { InheritEnvironmentSchema } from "../../core/agent-environment.js";
+import { DurationSchema } from "../../core/duration.js";
+import { antigravityCatalog, applyCatalogEffort } from "../../core/index.js";
+
+export const AntigravityDriverConfigSchema = z
+  .object({
+    command: z.string().min(1).default("agy"),
+    /** Antigravity model slugs often bake in an effort; never inherit the CLI default. */
+    model: z.string().min(1),
+    /** Pin coding mode: an inherited plan mode makes sandboxed workspaces read-only. */
+    mode: z.enum(["accept-edits", "plan"]).default("accept-edits"),
+    reasoningEffort: z.enum(antigravityCatalog.efforts).optional(),
+    agent: z.string().min(1).optional(),
+    /** Use an existing project; otherwise each run creates a fresh project. */
+    project: z.string().min(1).optional(),
+    addDirs: z.array(z.string().min(1)).default([]),
+    /**
+     * Auto-approve every tool permission. Off by default: a headless turn that
+     * needs approval can report WAITING or SUCCESS with denied_actions; both fail.
+     */
+    skipPermissions: z.boolean().default(false),
+    /** Enable Antigravity's terminal sandbox restrictions. */
+    sandbox: z.boolean().default(false),
+    /** Own the CLI settings in a private runtime home instead of changing user settings. */
+    permissionMode: z.enum(["inherit", "proceed-in-sandbox"]).default("inherit"),
+    permissions: z
+      .object({
+        allow: z.array(z.string().min(1)).default([]),
+        deny: z.array(z.string().min(1)).default([]),
+        ask: z.array(z.string().min(1)).default([]),
+      })
+      .strict()
+      .optional(),
+    /** Optional CLI-format OAuth token file for the private runtime; never logged. */
+    authTokenFile: z.string().min(1).optional(),
+    /** Explicitly authorize copying this application's macOS Keychain credential. */
+    reuseKeychain: z.boolean().default(false),
+    cwd: z.string().optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    inheritEnv: InheritEnvironmentSchema.optional(),
+    extraArgs: z.array(z.string()).optional(),
+    idleTimeout: DurationSchema.default("10 minutes"),
+    maxLineBytes: z.number().positive().default(10_000_000),
+  })
+  .strict()
+  .superRefine((config, ctx) => {
+    if (config.permissionMode === "proceed-in-sandbox") {
+      if (!config.sandbox || config.skipPermissions)
+        ctx.addIssue({
+          code: "custom",
+          message: "proceed-in-sandbox requires sandbox: true and skipPermissions: false",
+        });
+      if (config.project)
+        ctx.addIssue({
+          code: "custom",
+          path: ["project"],
+          message: "A private Antigravity runtime cannot reuse a host project",
+        });
+    } else if (config.permissions || config.authTokenFile || config.reuseKeychain) {
+      ctx.addIssue({
+        code: "custom",
+        message:
+          "permissions, authTokenFile, and reuseKeychain require permissionMode: proceed-in-sandbox",
+      });
+    }
+  })
+  .transform(applyCatalogEffort(antigravityCatalog));
+
+export type AntigravityDriverConfig = z.infer<typeof AntigravityDriverConfigSchema>;
+
+export const buildAntigravityArgs = (config: AntigravityDriverConfig, cwd?: string): string[] => [
+  "--input-format",
+  "stream-json",
+  "--output-format",
+  "stream-json",
+  "--model",
+  config.model,
+  "--mode",
+  config.mode,
+  ...(config.project ? ["--project", config.project] : ["--new-project"]),
+  ...(cwd ? ["--add-dir", cwd] : []),
+  ...config.addDirs.flatMap((directory) => ["--add-dir", directory]),
+  ...(config.reasoningEffort ? ["--effort", config.reasoningEffort] : []),
+  ...(config.agent ? ["--agent", config.agent] : []),
+  ...(config.skipPermissions ? ["--dangerously-skip-permissions"] : []),
+  ...(config.sandbox ? ["--sandbox"] : []),
+  ...(config.extraArgs ?? []),
+];
+
+export const formatAntigravityPrompt = (prompt: string): string =>
+  JSON.stringify({ event: "user", message: { content: prompt } });