@dna113p/machines 0.1.0 → 0.2.0

package/README.md

@@ -63,6 +63,7 @@ Run it with `node demo.ts`. No build is needed to develop against the source.
 | Agent escalation | `npm run example:agents` | Built-in fake runners |
 | Child host and Human response | `npm run example:host` | Node only |
 | Real Agent writes and verifies a file | `npm run example:pi` | Configured Pi through `pi-acp`; may use network and model credits |
+| Real AGY writes and verifies a file | `npm run example:agy` | Configured Antigravity CLI (`agy`); may use network and model credits |
 
 ## Run your own workflows
 
@@ -140,7 +141,7 @@ npm pack
 Then install the generated `dna113p-machines-0.1.0.tgz` into a project:
 
 ```bash
-npm install /absolute/path/to/machines/dna113p-machines-0.1.0.tgz
+npm install /absolute/path/to/machines/dna113p-machines-0.2.0.tgz
 npx machine list
 ```
 
@@ -173,6 +174,11 @@ workflow decisions in Human states. The launcher defaults unnamed Agents to
 `npx -y pi-acp`; [Agent presets](docs/authoring.md#agent-presets) let you select
 another ACP command or runner explicitly.
 
+The built-in `agy` preset selects the Antigravity CLI with AGY permission checks
+enabled. [AGY configuration](docs/authoring.md#antigravity-agy) explains runner
+settings and explicit opt-in to automatic tool approval. `npm run example:agy`
+opts in for its temporary-directory demonstration.
+
 ## Checks
 
 ```bash
@@ -183,4 +189,21 @@ npm run build:plugin
 npm run smoke:plugin   # exercise a relocated standalone plugin
 ```
 
+## Releasing
+
+The [publishing workflow](.github/workflows/publish.yml) uses a standard GitHub
+runner and npm trusted publishing, without an npm token stored in GitHub.
+Pushing a `vX.Y.Z` tag runs the checks above and publishes to npm if they pass.
+The tag must match the stable version in `package.json`.
+
+For example, to release the next minor version from an up-to-date, clean `main`:
+
+```bash
+npm version minor
+git push origin main --follow-tags
+```
+
+Running **Publish to npm** manually in GitHub Actions performs the checks and a
+publishing dry run; it does not publish a package.
+
 Licensed under the [MIT License](LICENSE).

package/dist/examples/agy.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/agy.js

@@ -0,0 +1,30 @@
+import { mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { agent, final, machine, operation, run, } from "../src/index.js";
+import { agyAgent } from "../src/agy.js";
+const workspace = await mkdtemp(join(tmpdir(), "machines-agy-"));
+const helloPath = join(workspace, "hello.txt");
+const example = machine({
+    initial: "write",
+    states: {
+        write: agent("Create hello.txt containing exactly: Hello from Machines.", { completed: "verify" }, { cwd: workspace }),
+        verify: operation(async () => {
+            const content = await readFile(helloPath, "utf8");
+            if (content.trim() !== "Hello from Machines.") {
+                throw new Error("hello.txt did not contain the expected text");
+            }
+            return { type: "passed" };
+        }, { passed: "done" }),
+        done: final(),
+    },
+});
+const result = await run(example, {
+    agents: {
+        // This demo explicitly permits unattended tools in its temporary workspace.
+        default: agyAgent("agy", [], { dangerouslySkipPermissions: true }),
+    },
+});
+console.log(`agy workspace: ${workspace}`);
+console.log(`hello.txt: ${(await readFile(helloPath, "utf8")).trim()}`);
+console.log(`verified --> ${String(result.value)}`);

package/dist/src/acp.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { Readable, Writable } from "node:stream";
 import * as acp from "@agentclientprotocol/sdk";
+import { agentPrompt, readAgentEvent } from "./agent-protocol.js";
 export function acpAgent(command, args = [], options = {}) {
     return async (request, report) => {
         if (request.cwd === undefined) {
@@ -112,7 +113,7 @@ async function runSession(child, request, outputMode, report, harness) {
         if (result.stopReason !== "end_turn") {
             throw new Error(`ACP Agent stopped with "${result.stopReason}"`);
         }
-        return returnedEvent(output, outputMode === "capture");
+        return readAgentEvent(output, { adapter: "ACP", includeMessage: outputMode === "capture" });
     });
 }
 function identityUpdate(options, harness) {
@@ -137,45 +138,6 @@ function identityUpdate(options, harness) {
             ...(thinking === undefined ? {} : { thinking }),
         };
 }
-function agentPrompt(request) {
-    return [
-        request.prompt,
-        "",
-        "Complete the work using the available tools.",
-        `Allowed outcome types: ${request.outcomes.join(", ")}.`,
-        "When finished, end your final response with exactly one line in this form:",
-        'MACHINES_EVENT {"type":"completed"}',
-        "Replace completed with exactly one allowed outcome type.",
-        "Include additional JSON fields only when the task asks for them.",
-    ].join("\n");
-}
-function returnedEvent(output, includeMessage) {
-    const matches = [...output.matchAll(/^MACHINES_EVENT (.+)$/gmu)];
-    const encoded = matches.at(-1)?.[1];
-    if (encoded === undefined) {
-        throw new Error("ACP Agent finished without returning a Machines event");
-    }
-    let event;
-    try {
-        event = JSON.parse(encoded);
-    }
-    catch (cause) {
-        throw new Error("ACP Agent returned invalid event JSON", { cause });
-    }
-    if (event === null
-        || typeof event !== "object"
-        || !("type" in event)
-        || typeof event.type !== "string") {
-        throw new Error("ACP Agent returned an invalid Machines event");
-    }
-    const result = event;
-    const message = output
-        .replace(/^MACHINES_EVENT .+$(?:\r?\n)?/gmu, "")
-        .trim();
-    return includeMessage && message !== ""
-        ? { ...result, message }
-        : result;
-}
 function waitForSpawn(child) {
     return new Promise((resolve, reject) => {
         child.once("spawn", resolve);

package/dist/src/agent-protocol.d.ts

@@ -0,0 +1,6 @@
+import type { AgentRequest, Event } from "./index.ts";
+export declare function agentPrompt(request: AgentRequest): string;
+export declare function readAgentEvent(output: string, options: {
+    readonly adapter: string;
+    readonly includeMessage: boolean;
+}): Event;

package/dist/src/agent-protocol.js

@@ -0,0 +1,38 @@
+export function agentPrompt(request) {
+    return [
+        request.prompt,
+        "",
+        "Complete the work using the available tools.",
+        `Allowed outcome types: ${request.outcomes.join(", ")}.`,
+        "When finished, end your final response with exactly one line in this form:",
+        'MACHINES_EVENT {"type":"completed"}',
+        "Replace completed with exactly one allowed outcome type.",
+        "Include additional JSON fields only when the task asks for them.",
+    ].join("\n");
+}
+export function readAgentEvent(output, options) {
+    const matches = [...output.matchAll(/^MACHINES_EVENT (.+)$/gmu)];
+    const encoded = matches.at(-1)?.[1];
+    if (encoded === undefined) {
+        throw new Error(`${options.adapter} Agent finished without returning a Machines event`);
+    }
+    let event;
+    try {
+        event = JSON.parse(encoded);
+    }
+    catch (cause) {
+        throw new Error(`${options.adapter} Agent returned invalid event JSON`, { cause });
+    }
+    if (!isEvent(event)) {
+        throw new Error(`${options.adapter} Agent returned an invalid Machines event`);
+    }
+    const message = output.replace(/^MACHINES_EVENT .+$(?:\r?\n)?/gmu, "").trim();
+    return options.includeMessage && message !== "" ? { ...event, message } : event;
+}
+function isEvent(value) {
+    return value !== null
+        && typeof value === "object"
+        && !Array.isArray(value)
+        && "type" in value
+        && typeof value.type === "string";
+}

package/dist/src/agy.d.ts

@@ -0,0 +1,11 @@
+import type { AgentRunner } from "./index.ts";
+export interface AgyAgentOptions {
+    readonly env?: Readonly<Record<string, string>>;
+    readonly harness?: string;
+    readonly model?: string;
+    readonly effort?: "low" | "medium" | "high";
+    /** Explicitly opt in to auto-approving all AGY tool permission requests. */
+    readonly dangerouslySkipPermissions?: boolean;
+    readonly output?: "capture" | "stream";
+}
+export declare function agyAgent(command?: string, args?: readonly string[], options?: AgyAgentOptions): AgentRunner;

package/dist/src/agy.js

@@ -0,0 +1,168 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import * as v from "valibot";
+import { agentPrompt, readAgentEvent } from "./agent-protocol.js";
+export function agyAgent(command = "agy", args = [], options = {}) {
+    return async (request, report) => {
+        if (request.cwd === undefined) {
+            throw new Error("agy Agent requires a working directory");
+        }
+        if (request.outcomes.length === 0) {
+            throw new Error("agy Agent requires at least one allowed outcome");
+        }
+        const harness = options.harness ?? (command === "agy" ? "agy" : command);
+        const env = { ...process.env, ...options.env };
+        const model = options.model ?? env.AGY_MODEL ?? env.MACHINES_AGENT_MODEL;
+        const effort = options.effort ?? env.AGY_EFFORT ?? env.MACHINES_AGENT_EFFORT;
+        const outputMode = options.output ?? "stream";
+        report?.({
+            type: "identity",
+            harness,
+            ...(model === undefined ? {} : { model }),
+            ...(effort === undefined ? {} : { thinking: effort }),
+        });
+        const cliArgs = [
+            ...args,
+            "--print",
+            agentPrompt(request),
+            "--output-format",
+            "stream-json",
+            "--disable-slash-commands",
+            ...(options.dangerouslySkipPermissions === true ? ["--dangerously-skip-permissions"] : []),
+            ...(model === undefined ? [] : ["--model", model]),
+            ...(effort === undefined ? [] : ["--effort", effort]),
+        ];
+        const child = spawn(command, cliArgs, {
+            cwd: request.cwd,
+            env,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stderr = "";
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+            if (outputMode === "stream")
+                process.stderr.write(chunk);
+        });
+        try {
+            await waitForSpawn(child);
+            return await runSession(child, outputMode, report);
+        }
+        catch (cause) {
+            const message = cause instanceof Error ? cause.message : String(cause);
+            const detail = stderr.trim();
+            throw new Error(`agy Agent "${command}" failed in "${request.cwd}": ${message}${detail === "" ? "" : `\n${detail}`}`, { cause });
+        }
+        finally {
+            child.kill();
+        }
+    };
+}
+async function runSession(child, outputMode, report) {
+    const exited = new Promise((resolve, reject) => {
+        child.once("close", (code, signal) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(signal === null
+                    ? `Process exited with code ${code}`
+                    : `Process terminated by ${signal}`));
+        });
+        child.once("error", reject);
+    });
+    // Observe failures immediately, while stdout may still be draining.
+    void exited.catch(() => { });
+    const lines = createInterface({ input: child.stdout });
+    let displayedOutput = "";
+    let finalResponse;
+    const emitOutput = (text) => {
+        if (text === "")
+            return;
+        displayedOutput += text;
+        report?.({ type: "output", text });
+        if (outputMode === "stream")
+            process.stdout.write(text);
+    };
+    try {
+        for await (const line of lines) {
+            const record = decodeRecord(line);
+            if (record === undefined)
+                continue;
+            if (record.event === "result") {
+                finalResponse = record.result.response;
+            }
+            else {
+                const step = record.step_update;
+                if (step.step_type === "agent_response") {
+                    emitOutput(step.text_delta);
+                }
+                else {
+                    const id = String(step.step_index ?? step.tool_name ?? "tool");
+                    const title = step.tool_name ?? step.tool_info?.name ?? "tool";
+                    const status = step.state === "ACTIVE"
+                        ? "in_progress"
+                        : (step.state === "DONE" ? "completed" : undefined);
+                    report?.({ type: "tool", id, title, ...(status === undefined ? {} : { status }) });
+                }
+            }
+        }
+        await exited;
+        // The final response owns the outcome; earlier deltas may contain progress
+        // or a preliminary event. Fall back only when no final response was sent.
+        const response = finalResponse ?? displayedOutput;
+        if (finalResponse !== undefined && !displayedOutput.endsWith(finalResponse)) {
+            if (finalResponse.startsWith(displayedOutput)) {
+                emitOutput(finalResponse.slice(displayedOutput.length));
+            }
+            else {
+                const separator = displayedOutput !== "" && !displayedOutput.endsWith("\n") ? "\n" : "";
+                emitOutput(separator + finalResponse);
+            }
+        }
+        if (outputMode === "stream" && displayedOutput !== "" && !displayedOutput.endsWith("\n")) {
+            process.stdout.write("\n");
+        }
+        return readAgentEvent(response, { adapter: "agy", includeMessage: outputMode === "capture" });
+    }
+    finally {
+        lines.close();
+    }
+}
+// Unknown events and malformed records are ignored at the transport boundary.
+// Only these validated fields can reach the harness-neutral AgentUpdate API.
+const recordSchema = v.variant("event", [
+    v.object({
+        event: v.literal("step_update"),
+        step_update: v.variant("step_type", [
+            v.object({ step_type: v.literal("agent_response"), text_delta: v.string() }),
+            v.object({
+                step_type: v.literal("tool"),
+                step_index: v.nullish(v.union([v.string(), v.number()])),
+                tool_name: v.nullish(v.string()),
+                tool_info: v.nullish(v.object({ name: v.nullish(v.string()) })),
+                state: v.nullish(v.string()),
+            }),
+        ]),
+    }),
+    v.object({
+        event: v.literal("result"),
+        result: v.object({ response: v.string() }),
+    }),
+]);
+function decodeRecord(line) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    const result = v.safeParse(recordSchema, value);
+    return result.success ? result.output : undefined;
+}
+function waitForSpawn(child) {
+    return new Promise((resolve, reject) => {
+        child.once("spawn", resolve);
+        child.once("error", reject);
+    });
+}

package/dist/src/catalog.js

@@ -1,5 +1,6 @@
 import { loadAgentBindings } from "./agent-bindings.js";
 import { acpAgent } from "./acp.js";
+import { agyAgent } from "./agy.js";
 import { discoverMachines, machinesUserHome } from "./discovery.js";
 import { loadMachineModule, readAgentRoles, requireMachineDescription } from "./machine-module.js";
 export async function inspectMachines(location = {}) {
@@ -45,22 +46,31 @@ export async function inspectAgentPresets(location = {}) {
         .sort((left, right) => left.name.localeCompare(right.name));
 }
 export async function configuredAgentPresets(cwd, home) {
-    const configured = await loadAgentBindings(cwd, home, { acpAgent });
+    const configured = await loadAgentBindings(cwd, home, { acpAgent, agyAgent });
     const defaultRunner = acpAgent("npx", ["-y", "pi-acp"], {
         harness: "pi-acp",
         output: "capture",
     });
+    const agyRunner = agyAgent("agy", [], {
+        harness: "agy",
+        output: "capture",
+    });
     return {
-        agents: { default: defaultRunner, ...configured.agents },
+        agents: { default: defaultRunner, agy: agyRunner, ...configured.agents },
         presets: {
             default: {
                 description: "Runs the current Pi Agent through ACP",
                 harness: "pi-acp",
                 runner: defaultRunner,
             },
+            agy: {
+                description: "Runs the Antigravity CLI (agy)",
+                harness: "agy",
+                runner: agyRunner,
+            },
             ...configured.presets,
         },
-        sources: { default: "built in", ...configured.sources },
+        sources: { default: "built in", agy: "built in", ...configured.sources },
     };
 }
 function errorMessage(cause) {

package/docs/architecture.md

@@ -41,6 +41,8 @@ MCP server ────┘       ↑
 | `src/machine-module.ts` | Shared module contract and metadata validation |
 | `src/catalog.ts` | Definition and preset catalog reads |
 | `src/acp.ts` | ACP process/session protocol, bounded Agent result, normalized activity |
+| `src/agy.ts` | Antigravity CLI (agy) process protocol, bounded Agent result, normalized activity |
+| `src/agent-protocol.ts` | Shared Agent prompt instructions and Machines event decoding |
 | `src/discovery.ts` | Project/global definition locations and precedence |
 | `src/launcher.ts` | Definition metadata, Agent bindings, preflight, single-use launch preparation |
 | `src/discovery-worker.ts` | Fresh metadata imports in disposable workers |

package/docs/authoring.md

@@ -140,7 +140,7 @@ export default ({ acpAgent }: { acpAgent: typeof import("@dna113p/machines/acp")
 Install/configure the selected harness and its model credentials first. `acpAgent`
 accepts any compatible ACP command and argument array; the Pi adapter uses ACP as
 its supported execution path. The former `machines/pi` export has been retired;
-use `acpAgent` from `machines/acp` for Pi execution.
+use `acpAgent` from `@dna113p/machines/acp` for Pi execution.
 
 Global presets live in `~/.machines/agents.ts`; project presets replace matching
 global names. Each preset requires a description and runner. Optional `harness`,
@@ -161,6 +161,45 @@ reports missing bindings or invalid definitions.
 `ready` describes valid metadata and resolved roles; it does not verify that a
 real harness is installed, authenticated, or able to run the requested model.
 
+### Antigravity (AGY)
+
+The built-in `agy` preset runs the installed Antigravity CLI. Select it for the
+default Agent or a declared named role:
+
+```bash
+machine run my-workflow --agent default=agy -- "Do the task"
+machine run review-task --agent implementer=agy -- "Implement the task"
+```
+
+The runner keeps AGY's permission checks enabled. It does not forward interactive
+permission prompts through Machines. For an unattended workflow that requires
+automatic approval, configure an explicit preset in `.machines/agents.ts`:
+
+```ts
+export default ({ agyAgent }: { agyAgent: typeof import("@dna113p/machines/agy").agyAgent }) => ({
+  "agy-unattended": {
+    description: "Runs AGY with automatic tool approval for trusted workflows",
+    harness: "agy",
+    runner: agyAgent("agy", [], {
+      dangerouslySkipPermissions: true,
+      output: "capture",
+    }),
+  },
+});
+```
+
+Select that preset with `--agent default=agy-unattended`. The option
+`dangerouslySkipPermissions: true` auto-approves all AGY tool permission requests;
+omitting it or setting it to `false` keeps the runner from adding that flag.
+The `example:agy` demonstration explicitly opts in and asks AGY to work in a
+temporary directory.
+
+Runner `model` and `effort` options take precedence over environment settings.
+Otherwise it uses `AGY_MODEL` / `AGY_EFFORT`, falling back to
+`MACHINES_AGENT_MODEL` / `MACHINES_AGENT_EFFORT`. Per-runner `env` values override
+the same variables inherited from the parent process. Effort values are `low`,
+`medium`, or `high`.
+
 ## Programmatic execution and verification
 
 Direct runtime users supply runners through `run(definition, { agents, human })`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dna113p/machines",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Reusable workflows coordinating agents, local operations, and human decisions.",
   "license": "MIT",
   "repository": {
@@ -22,6 +22,7 @@
   "exports": {
     ".": { "types": "./dist/src/index.d.ts", "import": "./dist/src/index.js" },
     "./acp": { "types": "./dist/src/acp.d.ts", "import": "./dist/src/acp.js" },
+    "./agy": { "types": "./dist/src/agy.d.ts", "import": "./dist/src/agy.js" },
     "./launcher": { "types": "./dist/src/launcher.d.ts", "import": "./dist/src/launcher.js" },
     "./mcp": { "types": "./dist/mcp/server.d.ts", "import": "./dist/mcp/server.js" },
     "./pi-extension": { "types": "./dist/pi-extension/index.d.ts", "import": "./dist/pi-extension/index.js" }
@@ -33,6 +34,7 @@
     "check": "npm run typecheck && npm test",
     "example": "node examples/operation.ts",
     "example:agents": "node examples/named-agents.ts",
+    "example:agy": "node examples/agy.ts",
     "example:host": "node examples/host.ts",
     "example:pi": "node examples/pi.ts",
     "mcp": "node mcp/server.ts",