@agentproto/driver-agent-cli 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentproto contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/chunk-EEIYDRIU.mjs

@@ -0,0 +1,552 @@
+import { z } from 'zod';
+import { Writable, Readable } from 'stream';
+import { createAcpClient } from '@agentproto/acp/client';
+import { spawn } from 'child_process';
+import { randomUUID } from 'crypto';
+import { createDoctype } from '@agentproto/define-doctype';
+
+/**
+ * @agentproto/driver-agent-cli v0.1.0-alpha
+ * AIP-45 AGENT-CLI.md `defineAgentCli` reference implementation.
+ */
+
+var ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,63}$/;
+var SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/;
+var TAG_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+var SEMVER_RANGE_PATTERN = /^[><=^~ \d.\-+\w*xX|, ]+$/;
+var ADAPTER_PATTERN = /^@?[a-z0-9][a-z0-9-./]*$/;
+var BIN_PATTERN = /^[A-Za-z0-9._\-/]+$/;
+var MODE_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+var OPTION_ID_PATTERN = /^[a-z0-9][a-z0-9_]{0,63}$/;
+var CONTINUATION_STRATEGY_IDS = [
+  "none",
+  "pinned-session",
+  "transcript",
+  "native-resume"
+];
+var CONTINUATION_KEY_SCOPES = [
+  "conversation",
+  "operator",
+  "user",
+  "guild",
+  "workspace"
+];
+var installMethodSchema = z.discriminatedUnion("method", [
+  z.object({ method: z.literal("brew"), package: z.string(), experimental: z.boolean().optional() }).strict(),
+  z.object({ method: z.literal("apt"), package: z.string(), experimental: z.boolean().optional() }).strict(),
+  z.object({ method: z.literal("dnf"), package: z.string(), experimental: z.boolean().optional() }).strict(),
+  z.object({ method: z.literal("pacman"), package: z.string(), experimental: z.boolean().optional() }).strict(),
+  z.object({ method: z.literal("choco"), package: z.string(), experimental: z.boolean().optional() }).strict(),
+  z.object({ method: z.literal("scoop"), package: z.string(), experimental: z.boolean().optional() }).strict(),
+  z.object({ method: z.literal("npm"), package: z.string(), global: z.boolean().optional(), experimental: z.boolean().optional() }).strict(),
+  z.object({ method: z.literal("pip"), package: z.string(), user: z.boolean().optional(), experimental: z.boolean().optional() }).strict(),
+  z.object({ method: z.literal("cargo"), package: z.string(), experimental: z.boolean().optional() }).strict(),
+  z.object({ method: z.literal("go"), package: z.string(), experimental: z.boolean().optional() }).strict(),
+  z.object({
+    method: z.literal("curl"),
+    url: z.string().url(),
+    verify_sha256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    experimental: z.boolean().optional()
+  }).strict(),
+  z.object({
+    method: z.literal("download"),
+    url: z.string().url(),
+    extract_bin: z.string(),
+    verify_sha256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    experimental: z.boolean().optional()
+  }).strict(),
+  z.object({ method: z.literal("vendored"), path: z.string(), experimental: z.boolean().optional() }).strict()
+]);
+var versionCheckSchema = z.object({
+  cmd: z.string(),
+  parse: z.string().describe("ECMAScript regex with at least one capture group."),
+  range: z.string().regex(SEMVER_RANGE_PATTERN).describe("npm-style semver range."),
+  timeout_ms: z.number().int().min(100).default(5e3)
+}).strict();
+var authSchema = z.object({
+  ref: z.string().optional(),
+  state: z.object({
+    paths: z.array(z.string()).optional(),
+    env: z.array(z.string()).optional()
+  }).strict().optional(),
+  login: z.object({
+    cmd: z.string(),
+    interactive: z.boolean().optional(),
+    requires_callback_url: z.boolean().optional()
+  }).strict().optional(),
+  refresh: z.object({
+    cmd: z.string(),
+    interval_s: z.number().int().positive().optional()
+  }).strict().optional(),
+  expiry: z.object({
+    parse: z.string().optional(),
+    grace_s: z.number().int().nonnegative().optional()
+  }).strict().optional()
+}).strict();
+var sessionSchema = z.object({
+  mode: z.enum(["ephemeral", "persistent", "resumable"]).default("ephemeral"),
+  idle_timeout_ms: z.number().int().min(1e3).default(6e5),
+  max_turns: z.number().int().positive().optional(),
+  context_carryover: z.boolean().default(true)
+}).strict();
+var modelsSchema = z.object({
+  default: z.string().optional(),
+  allowed: z.array(z.string()).optional(),
+  env: z.record(z.string(), z.string()).optional()
+}).strict();
+var capabilitiesSchema = z.object({
+  streaming: z.boolean().optional(),
+  tool_calls: z.boolean().optional(),
+  sub_agents: z.boolean().optional(),
+  file_io: z.boolean().optional(),
+  multimodal: z.boolean().optional(),
+  resumable: z.boolean().optional(),
+  bidirectional: z.boolean().optional()
+}).strict();
+var modeSchema = z.object({
+  id: z.string().regex(MODE_ID_PATTERN),
+  description: z.string().optional(),
+  bin_args_append: z.array(z.string()).optional(),
+  env: z.record(z.string(), z.string()).optional()
+}).strict();
+var optionSchema = z.object({
+  id: z.string().regex(OPTION_ID_PATTERN),
+  type: z.enum(["boolean", "integer", "string", "enum"]),
+  description: z.string().optional(),
+  enum: z.array(z.string()).min(1).optional(),
+  default: z.union([z.boolean(), z.number(), z.string()]).optional(),
+  min: z.number().int().optional(),
+  max: z.number().int().optional(),
+  bin_args_template: z.array(z.string()).optional(),
+  bin_args_append_when_true: z.array(z.string()).optional(),
+  env: z.record(z.string(), z.string()).optional()
+}).strict().refine(
+  // type === "enum" REQUIRES an `enum` array. The JSON Schema enforces
+  // this via `if/then`; the zod side mirrors with a refine so both
+  // validation paths reject the same shapes.
+  (o) => o.type !== "enum" || Array.isArray(o.enum) && o.enum.length > 0,
+  { message: "option.type === 'enum' requires a non-empty `enum` array" }
+);
+var continuationStrategyIdSchema = z.enum(CONTINUATION_STRATEGY_IDS);
+var continuationSchema = z.object({
+  default: continuationStrategyIdSchema,
+  supported: z.array(continuationStrategyIdSchema).min(1),
+  pinned_session: z.object({
+    idle_timeout_ms: z.number().int().min(1e3).default(18e5),
+    key_scope: z.array(z.enum(CONTINUATION_KEY_SCOPES)).min(1).default(["conversation", "operator"])
+  }).strict().optional()
+}).strict().refine(
+  // The chosen `default` must appear in `supported` — otherwise the
+  // host has no valid strategy to fall back to.
+  (c) => c.supported.includes(c.default),
+  {
+    message: "continuation.default must be a member of continuation.supported"
+  }
+);
+var mcpBlockSchema = z.object({
+  command: z.string().optional(),
+  args: z.array(z.string()).optional(),
+  transport: z.enum(["stdio", "http", "sse"]),
+  url: z.string().url().optional()
+}).strict();
+var agentCliFrontmatterSchema = z.object({
+  name: z.string().min(1).max(80),
+  id: z.string().regex(ID_PATTERN),
+  description: z.string().min(1).max(2e3),
+  version: z.string().regex(SEMVER_PATTERN),
+  bin: z.string().regex(BIN_PATTERN),
+  bin_args: z.array(z.string()).optional(),
+  install: z.array(installMethodSchema).min(1),
+  version_check: versionCheckSchema,
+  auth: authSchema.optional(),
+  sandbox: z.union([z.string(), z.record(z.string(), z.unknown())]),
+  runner: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
+  protocol: z.enum(["acp", "mcp", "proprietary"]),
+  acp: z.string().optional(),
+  mcp: mcpBlockSchema.optional(),
+  adapter: z.string().regex(ADAPTER_PATTERN).optional(),
+  session: sessionSchema.optional(),
+  models: modelsSchema.optional(),
+  capabilities: capabilitiesSchema.optional(),
+  modes: z.array(modeSchema).optional(),
+  options: z.array(optionSchema).optional(),
+  continuation: continuationSchema.optional(),
+  requires: z.object({
+    os: z.array(z.enum(["darwin", "linux", "windows"])).optional(),
+    arch: z.array(z.enum(["x64", "arm64", "x86", "arm"])).optional(),
+    min_disk_mb: z.number().int().nonnegative().optional(),
+    min_memory_mb: z.number().int().nonnegative().optional()
+  }).strict().optional(),
+  examples: z.array(z.object({
+    goal: z.string(),
+    prompt: z.string(),
+    note: z.string().optional()
+  }).strict()).optional(),
+  tags: z.array(z.string().regex(TAG_PATTERN)).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional()
+}).strict().superRefine((m, ctx) => {
+  if (m.modes) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const mode of m.modes) {
+      if (seen.has(mode.id)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["modes"],
+          message: `Duplicate mode id '${mode.id}' \u2014 mode ids must be unique within a manifest.`
+        });
+      }
+      seen.add(mode.id);
+    }
+  }
+  if (m.options) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const opt of m.options) {
+      if (seen.has(opt.id)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["options"],
+          message: `Duplicate option id '${opt.id}' \u2014 option ids must be unique within a manifest.`
+        });
+      }
+      seen.add(opt.id);
+    }
+  }
+  if (m.continuation?.default === "native-resume" && !m.capabilities?.resumable) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["continuation", "default"],
+      message: "continuation.default === 'native-resume' requires capabilities.resumable: true."
+    });
+  }
+}).describe(
+  "Validates the YAML frontmatter portion of an AIP-45 AGENT-CLI.md manifest."
+);
+var runtimeConfigSchema = z.object({
+  mode: z.string().optional(),
+  options: z.record(z.string(), z.union([z.boolean(), z.number(), z.string()])).optional(),
+  continuation: continuationStrategyIdSchema.optional()
+}).strict();
+function createAcpProtocolArm(options) {
+  const { child, cwd } = options;
+  if (!child.stdin || !child.stdout) {
+    throw new Error(
+      "AcpProtocolArm: subprocess must be spawned with piped stdin + stdout"
+    );
+  }
+  const output = Writable.toWeb(child.stdin);
+  const input = Readable.toWeb(child.stdout);
+  let client = null;
+  let session = null;
+  const pendingByTurn = /* @__PURE__ */ new Map();
+  return {
+    get sessionId() {
+      return session?.sessionId;
+    },
+    async connect(opts) {
+      client = await createAcpClient({
+        output,
+        input,
+        clientInfo: options.clientInfo,
+        capabilities: {
+          fs: { readTextFile: true, writeTextFile: true }
+        }
+      });
+      if (opts.resumeSessionId) {
+        session = await client.loadSession({
+          sessionId: opts.resumeSessionId,
+          cwd
+        });
+      } else {
+        session = await client.newSession({ cwd });
+      }
+    },
+    async send(turnId, message) {
+      if (!session) throw new Error("AcpProtocolArm.send: not connected");
+      const messages = Array.isArray(message) ? message : [message];
+      const stream = session.prompt({ messages });
+      pendingByTurn.set(turnId, stream);
+    },
+    async *events() {
+      const last = Array.from(pendingByTurn.values()).at(-1);
+      if (!last) return;
+      for await (const evt of last) yield evt;
+    },
+    async cancel(_turnId) {
+      if (!session) return;
+      await session.cancel();
+    },
+    async close() {
+      if (session) await session.close();
+      if (client) await client.close();
+    }
+  };
+}
+
+// src/manifest/compose.ts
+var RuntimeConfigError = class extends Error {
+  code;
+  path;
+  constructor(code, path, message) {
+    super(`[${code} at ${path}] ${message}`);
+    this.code = code;
+    this.path = path;
+    this.name = "RuntimeConfigError";
+  }
+};
+function composeSpawn(handle, config) {
+  const binArgs = [...handle.bin_args ?? []];
+  const env = {};
+  if (!config) return { binArgs, env };
+  if (config.mode !== void 0) {
+    const mode = (handle.modes ?? []).find((m) => m.id === config.mode);
+    if (!mode) {
+      const known = (handle.modes ?? []).map((m) => m.id).join(", ") || "(none)";
+      throw new RuntimeConfigError(
+        "unknown_mode",
+        "config.mode",
+        `Mode '${config.mode}' is not declared by manifest '${handle.id}'. Known modes: ${known}`
+      );
+    }
+    if (mode.bin_args_append) binArgs.push(...mode.bin_args_append);
+    if (mode.env) Object.assign(env, mode.env);
+  }
+  if (config.options && Object.keys(config.options).length > 0) {
+    const declared = handle.options ?? [];
+    const declaredById = new Map(declared.map((o) => [o.id, o]));
+    for (const id of Object.keys(config.options)) {
+      if (!declaredById.has(id)) {
+        const known = declared.map((o) => o.id).join(", ") || "(none)";
+        throw new RuntimeConfigError(
+          "unknown_option",
+          `config.options.${id}`,
+          `Option '${id}' is not declared by manifest '${handle.id}'. Known options: ${known}`
+        );
+      }
+    }
+    for (const option of declared) {
+      if (!(option.id in config.options)) continue;
+      const value = config.options[option.id];
+      validateOptionValue(option, value);
+      const patch = renderOptionPatch(option, value);
+      binArgs.push(...patch.binArgs);
+      Object.assign(env, patch.env);
+    }
+  }
+  if (config.continuation !== void 0 && handle.continuation) {
+    if (!handle.continuation.supported.includes(config.continuation)) {
+      throw new RuntimeConfigError(
+        "unsupported_continuation",
+        "config.continuation",
+        `Continuation strategy '${config.continuation}' is not in manifest '${handle.id}'.continuation.supported (${handle.continuation.supported.join(", ")}).`
+      );
+    }
+  }
+  return { binArgs, env };
+}
+function resolveContinuationStrategy(handle, config) {
+  if (config?.continuation) return config.continuation;
+  return handle.continuation?.default ?? "none";
+}
+function validateOptionValue(option, value) {
+  const path = `config.options.${option.id}`;
+  switch (option.type) {
+    case "boolean":
+      if (typeof value !== "boolean") {
+        throw new RuntimeConfigError(
+          "option_type_mismatch",
+          path,
+          `Expected boolean, got ${typeof value} (${JSON.stringify(value)}).`
+        );
+      }
+      return;
+    case "integer":
+      if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new RuntimeConfigError(
+          "option_type_mismatch",
+          path,
+          `Expected integer, got ${typeof value === "number" ? "non-integer number" : typeof value} (${JSON.stringify(value)}).`
+        );
+      }
+      if (option.min !== void 0 && value < option.min) {
+        throw new RuntimeConfigError(
+          "option_bounds_violation",
+          path,
+          `Value ${value} is below the declared minimum ${option.min}.`
+        );
+      }
+      if (option.max !== void 0 && value > option.max) {
+        throw new RuntimeConfigError(
+          "option_bounds_violation",
+          path,
+          `Value ${value} is above the declared maximum ${option.max}.`
+        );
+      }
+      return;
+    case "string":
+      if (typeof value !== "string") {
+        throw new RuntimeConfigError(
+          "option_type_mismatch",
+          path,
+          `Expected string, got ${typeof value} (${JSON.stringify(value)}).`
+        );
+      }
+      return;
+    case "enum":
+      if (typeof value !== "string") {
+        throw new RuntimeConfigError(
+          "option_type_mismatch",
+          path,
+          `Expected string (enum value), got ${typeof value} (${JSON.stringify(value)}).`
+        );
+      }
+      if (!(option.enum ?? []).includes(value)) {
+        throw new RuntimeConfigError(
+          "option_enum_violation",
+          path,
+          `Value '${value}' is not in the declared enum (${(option.enum ?? []).join(", ")}).`
+        );
+      }
+      return;
+  }
+}
+function renderOptionPatch(option, value) {
+  const stringValue = String(value);
+  if (option.type === "boolean") {
+    if (value !== true) return { binArgs: [], env: {} };
+    return {
+      binArgs: option.bin_args_append_when_true ? [...option.bin_args_append_when_true] : [],
+      env: option.env ? interpolateEnv(option.env, stringValue) : {}
+    };
+  }
+  return {
+    binArgs: option.bin_args_template ? option.bin_args_template.map(
+      (token) => token.replace(/\{value\}/g, stringValue)
+    ) : [],
+    env: option.env ? interpolateEnv(option.env, stringValue) : {}
+  };
+}
+function interpolateEnv(env, value) {
+  const out = {};
+  for (const [k, v] of Object.entries(env)) {
+    out[k] = v.replace(/\{value\}/g, value);
+  }
+  return out;
+}
+var defineAgentCli = createDoctype(
+  {
+    aip: 45,
+    name: "agent-cli",
+    readIdentity: (def) => def.id,
+    validate(def) {
+      const result = agentCliFrontmatterSchema.safeParse(def);
+      if (!result.success) {
+        throw new Error(
+          `defineAgentCli (AIP-45): ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+        );
+      }
+      const data = result.data;
+      if (data.protocol === "acp" && !data.acp) {
+        throw new Error(
+          "defineAgentCli (AIP-45): `acp` ref is required when protocol=acp"
+        );
+      }
+      if (data.protocol === "mcp" && !data.mcp) {
+        throw new Error(
+          "defineAgentCli (AIP-45): `mcp` block is required when protocol=mcp"
+        );
+      }
+      if (data.protocol === "proprietary" && !data.adapter) {
+        throw new Error(
+          "defineAgentCli (AIP-45): `adapter` package is required when protocol=proprietary"
+        );
+      }
+      if (data.session?.mode === "resumable" && data.capabilities?.resumable !== true) {
+        throw new Error(
+          "defineAgentCli (AIP-45): session.mode=resumable requires capabilities.resumable: true"
+        );
+      }
+    },
+    build(def) {
+      return { ...def };
+    }
+  }
+);
+function createAgentCliRuntime(definition) {
+  return {
+    definition,
+    async start(opts) {
+      const cwd = opts?.cwd ?? process.cwd();
+      const composed = composeSpawn(definition, opts?.config);
+      const env = {
+        ...filterStringEnv(process.env),
+        ...composed.env,
+        ...opts?.env ?? {}
+      };
+      const child = spawn(definition.bin, composed.binArgs, {
+        cwd,
+        env,
+        stdio: ["pipe", "pipe", "pipe"],
+        signal: opts?.signal
+      });
+      const arm = buildProtocolArm(definition, child, cwd);
+      const abortController = new AbortController();
+      if (opts?.signal) {
+        opts.signal.addEventListener("abort", () => abortController.abort(), {
+          once: true
+        });
+      }
+      await arm.connect({
+        cwd,
+        env,
+        abortSignal: abortController.signal,
+        ...opts?.resumeSessionId ? { resumeSessionId: opts.resumeSessionId } : {}
+      });
+      const sessionId = arm.sessionId ?? randomUUID();
+      return {
+        sessionId,
+        send(message) {
+          const turnId = randomUUID();
+          return promptTurn(arm, turnId, message);
+        },
+        async cancel() {
+          abortController.abort();
+        },
+        async close() {
+          await arm.close();
+          if (!child.killed) child.kill("SIGTERM");
+        }
+      };
+    }
+  };
+}
+async function* promptTurn(arm, turnId, message) {
+  await arm.send(turnId, message);
+  for await (const evt of arm.events()) yield evt;
+}
+function buildProtocolArm(def, child, cwd) {
+  switch (def.protocol) {
+    case "acp":
+      return createAcpProtocolArm({
+        child,
+        cwd,
+        clientInfo: { name: def.id, version: def.version }
+      });
+    case "mcp":
+      throw new Error("createAgentCliRuntime: mcp protocol arm not yet implemented");
+    case "proprietary":
+      throw new Error(
+        "createAgentCliRuntime: proprietary protocol arm not yet implemented"
+      );
+  }
+}
+function filterStringEnv(env) {
+  const out = {};
+  for (const [k, v] of Object.entries(env)) {
+    if (typeof v === "string") out[k] = v;
+  }
+  return out;
+}
+
+export { RuntimeConfigError, agentCliFrontmatterSchema, composeSpawn, createAcpProtocolArm, createAgentCliRuntime, defineAgentCli, resolveContinuationStrategy, runtimeConfigSchema };
+//# sourceMappingURL=chunk-EEIYDRIU.mjs.map
+//# sourceMappingURL=chunk-EEIYDRIU.mjs.map