@alpacakit/agents 0.1.0-beta.19

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Masahiro Tonomura (codemafia0000)
+
+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/README.md

@@ -0,0 +1,224 @@
+# @alpacakit/agents
+
+Run AI coding agents programmatically: execute claude / codex / custom
+agents against a working directory, stream their output, classify
+failures, fail over across credentials and agents.
+
+Design: [`src/v2/design/l_agents_library.md`](https://github.com/alpacakit/alpacaloop/blob/main/src/v2/design/l_agents_library.md).
+
+The whole runtime surface — including extension points — ships from one
+root entry. Only genuine isolation lives on a subpath: dev fakes
+(`/testing`), the codex app-server client (`/codex`), the native keyring
+(`/keyring`), and machine-local config storage (`/config`).
+
+Most apps need only a handful of root exports: `runAgent`,
+`createAgentRuntime`, `processEnv`, the built-in `claude` / `codex`
+factories, `openaiCompatible`, `createFleet`, `candidateFromProfile` /
+`candidateForAgent`, `createHomeDirProfile` / `createApiKeyProfile`, and
+`AgentError` / `isAgentError`. Everything else on the root entry is an
+extension point (custom agents, guards, auth materials, host facets) you
+reach for only when extending the runtime.
+
+## Quick start
+
+```ts
+import { runAgent } from "@alpacakit/agents";
+
+const { text } = await runAgent({
+  agent: "claude", // or "codex"
+  workspace: "/work/repo",
+  prompt: "Summarize the failing tests.",
+});
+```
+
+`runAgent` is the minimal-persona sugar: it reads `process.env` by
+default and applies a documented 1-hour total timeout.
+
+## Runtime, streaming, and limits
+
+`createAgentRuntime` never reads `process.env` implicitly, so `baseEnv`
+is a **required** argument — omitting it can no longer silently produce an
+empty env that fails auth at run time. Pass the exported `processEnv()`
+snapshot for the ambient environment, or `{}` for a hermetic run.
+(`runAgent` above is the only entry that defaults `baseEnv` to
+`processEnv()`.)
+
+```ts
+import {
+  createAgentRuntime,
+  claude,
+  maxToolCalls,
+  processEnv,
+} from "@alpacakit/agents";
+
+const runtime = createAgentRuntime({ agents: [claude()], baseEnv: processEnv() });
+const handle = runtime.agent("claude").run({
+  prompt,
+  workspace,
+  sandbox: { mode: "read-only", grants: [{ kind: "shell", command: "git status" }] },
+  limits: { totalMs: 600_000, idleMs: 120_000, guards: [maxToolCalls(120)] },
+  signal: controller.signal,
+});
+for await (const event of handle.events) {
+  // started / output / message / turn / tool / trace / ended
+}
+const result = await handle; // await handle === await handle.result
+```
+
+## Structured output
+
+Any Standard Schema validator (zod v4 etc.) works. Repair happens within
+one structured run handle; an exhausted budget throws `AgentError` with
+`output_rejected`.
+
+```ts
+const { output } = await runtime.agent("claude").run({
+  prompt,
+  workspace,
+  contract: { schema: hintListSchema },
+});
+```
+
+`agent.run({ ..., contract })` returns an awaitable handle: `await` it
+for the result, or iterate `.events` to stream every repair attempt's run
+events as they happen (`for await (const event of handle.events) …`).
+
+## Failover across credentials and agents
+
+`fleet.run` runs the same raw or structured run options across ordered
+candidates. Each attempt is candidate-bound: auth env, model / effort
+defaults, and the linked abort signal are already folded in.
+
+```ts
+import {
+  candidateFromProfile,
+  createFleet,
+  createHomeDirProfile,
+  fileFleetStore,
+} from "@alpacakit/agents";
+
+const codexProfile = createHomeDirProfile({
+  id: "codex-work",
+  agentId: "codex",
+  path: "/home/me/.codex",
+});
+
+const fleet = createFleet({ runtime, store: fileFleetStore(statePath) });
+const outcome = await fleet.run({
+  candidates: [candidateFromProfile(codexProfile, { model: "gpt-5" })],
+  runOptions: { ...options, contract },
+});
+if (outcome.status === "deferred") schedule(outcome.earliestRetryAt);
+```
+
+## OpenAI-compatible and custom agents
+
+`openaiCompatible` needs only `id` / `baseUrl` / `model`; `apiKey`,
+`headers`, and `requestParams` default to absent. Any field may be an
+`${ENV_VAR}` template resolved against `baseEnv`.
+
+```ts
+import { createAgentRuntime, openaiCompatible } from "@alpacakit/agents";
+
+const runtime = createAgentRuntime({
+  agents: [openaiCompatible({ id: "ollama", baseUrl: "http://localhost:11434/v1", model: "llama3.1" })],
+  baseEnv: processEnv(),
+});
+```
+
+Add a whole new CLI agent with `defineCliAgent` (sandbox argv, line
+parsing, auth materials, and failure matchers are all keyed records — no
+`if`), or wrap any executor with `defineAgent`.
+
+## Machine-local config (`@alpacakit/agents/config`)
+
+`@alpacakit/agents/config` persists auth profiles, agent settings, and
+fleet state, then projects them into runtime primitives. It is
+convention-neutral: it never reads env or picks a home directory — the app
+supplies `rootDir` (and any secret resolvers) and wires the runtime.
+
+```ts
+import { createAgentRuntime, createFleet, processEnv } from "@alpacakit/agents";
+import {
+  candidatesForFleet,
+  loadAgentsRuntimeConfig,
+  secretsForRuntime,
+} from "@alpacakit/agents/config";
+
+const config = await loadAgentsRuntimeConfig({ rootDir });
+const runtime = createAgentRuntime({
+  agents: config.agents,
+  ports: { secrets: secretsForRuntime(config) },
+  baseEnv: processEnv(),
+});
+const fleet = createFleet({ runtime, store: config.fleetStateStore });
+const outcome = await fleet.run({
+  candidates: candidatesForFleet(config),
+  attempt: (agent) => agent.run({ prompt, workspace }),
+});
+```
+
+Register profiles and agent configs with plain string ids — no id
+factory to call:
+
+```ts
+import { openAgentsConfig, openAiCompatibleAgentConfig } from "@alpacakit/agents/config";
+
+const home = openAgentsConfig({ rootDir });
+await home.profiles.addHomeDir({ id: "codex-main", agentId: "codex", path: "/home/me/.codex" });
+await home.agentConfigs.add(
+  openAiCompatibleAgentConfig({ id: "ollama", baseUrl: "http://localhost:11434/v1", model: "llama3.1" }),
+);
+```
+
+Operator note: `config.candidates` also carries `source` provenance
+(which agent-config / profile produced each candidate) for control-plane
+bookkeeping; `candidatesForFleet` drops it for the common fleet path.
+
+The root config API is convention-neutral — the app supplies `rootDir`.
+For the common case, `@alpacakit/agents/config/xdg` resolves it from the
+XDG spec (`$XDG_CONFIG_HOME/<appName>/agents`):
+
+```ts
+import { resolveXdgAgentsConfigOptions } from "@alpacakit/agents/config/xdg";
+
+const config = await loadAgentsRuntimeConfig(
+  resolveXdgAgentsConfigOptions({ appName: "acme", homeDir: os.homedir(), env: process.env }),
+);
+```
+
+Family-specific conventions (a fixed path env var + a keyring service)
+belong in the consumer's own convention module, not in this package — they
+are a plain instance of the same preset shape.
+
+## Host plane: skills & MCP (operator)
+
+Agents expose optional `agent.skills` / `agent.mcp` / `agent.doctor`
+facets for provisioning and health checks. This surface is still
+aspirational: the first slice covers Claude local-dir skills and
+Claude / Codex stdio MCP registration; broad inventory and availability
+listing are in progress.
+
+## Package entries
+
+| Entry | Contents |
+|---|---|
+| `.` | runtime, fleet, structured output, auth materials, guards, errors, and every extension point |
+| `/config` | machine-local profile / agent-settings / fleet-state storage |
+| `/config/xdg` | XDG Base Directory config-root preset (general apps) |
+| `/config/extension` | custom agent-config kinds (`defineAgentConfigType`) |
+| `/testing` | `fakeExec`, `fakeClock`, `fakeAgent`, `fakeSecretResolver` — no subprocess ever spawns |
+| `/codex` | codex app-server JSON-RPC client (advanced) |
+| `/keyring` | `keyringResolver` (loads the optional `@napi-rs/keyring` peer) |
+
+## Status
+
+Implemented: kernel (runtime, run handle, guards, classification), CLI
+blueprint with built-in `claude()` / `codex()`, structured output with
+repair, fleet with cooldown / auth-mark stores, auth materials and secret
+resolvers, `openaiCompatible` (engine port; the built-in HTTP
+chat-completions engine is the dependency-free default), and the first
+host-plane skill / MCP implementations (Claude local-dir skills plus
+Claude / Codex stdio MCP registration). Not yet implemented: the
+in-process pi-session engine for `openaiCompatible`, GitHub / plugin skill
+installers, and availability listing for installed skills / MCP servers.

package/dist/agents/builtin.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The built-in agent registry: a single source of truth for the two
+ * bundled agent ids and their factories. `runAgent` binds them by id, and
+ * the config layer reuses `BUILTIN_AGENT_ID` for its agent-config kinds —
+ * so "codex"/"claude" is spelled once, not once per layer.
+ */
+import { claude } from "./claude.js";
+import { codex } from "./codex.js";
+export declare const BUILTIN_AGENT_ID: {
+    readonly codex: "codex";
+    readonly claude: "claude";
+};
+export type BuiltinAgentId = (typeof BUILTIN_AGENT_ID)[keyof typeof BUILTIN_AGENT_ID];
+/** Keyed record, not a branch: adding a built-in is adding an entry. */
+export declare const builtinAgentFactories: {
+    readonly claude: typeof claude;
+    readonly codex: typeof codex;
+};
+//# sourceMappingURL=builtin.d.ts.map

package/dist/agents/builtin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin.d.ts","sourceRoot":"","sources":["../../src/agents/builtin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,eAAO,MAAM,gBAAgB;;;CAGnB,CAAC;AAEX,MAAM,MAAM,cAAc,GACxB,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAE3D,wEAAwE;AACxE,eAAO,MAAM,qBAAqB;;;CAA6B,CAAC"}

package/dist/agents/builtin.js

@@ -0,0 +1,14 @@
+/**
+ * The built-in agent registry: a single source of truth for the two
+ * bundled agent ids and their factories. `runAgent` binds them by id, and
+ * the config layer reuses `BUILTIN_AGENT_ID` for its agent-config kinds —
+ * so "codex"/"claude" is spelled once, not once per layer.
+ */
+import { claude } from "./claude.js";
+import { codex } from "./codex.js";
+export const BUILTIN_AGENT_ID = {
+    codex: "codex",
+    claude: "claude",
+};
+/** Keyed record, not a branch: adding a built-in is adding an entry. */
+export const builtinAgentFactories = { claude, codex };

package/dist/agents/claude.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Built-in claude adapter (v1 E1/E2 argv kept verbatim):
+ * `claude -p [--model m] [--effort e] --output-format stream-json
+ *  --permission-mode <mode> [tool args] --verbose`, prompt on stdin.
+ * Read-only grants map to `--allowedTools` (`Bash(cmd:*)` for shell
+ * grants, the bare tool name otherwise); no grants means `--tools ""`.
+ */
+import { type FailureMatcher } from "../kernel/classify.js";
+import type { AgentDefinition } from "../kernel/definition.js";
+export declare const CLAUDE_CONFIG_DIR_ENV_VAR = "CLAUDE_CONFIG_DIR";
+export declare const CLAUDE_API_KEY_ENV_VAR = "ANTHROPIC_API_KEY";
+/**
+ * Structured quota signals in Claude CLI NDJSON output (v1 F2), scanned
+ * per line: rate_limit_event rejected (with resetsAt), api_error_status
+ * 429, and error === "rate_limit". Exported for custom agents that speak
+ * the same stream format.
+ */
+export declare function structuredQuotaMatcher(): FailureMatcher;
+export declare function claude(): AgentDefinition<"claude">;
+//# sourceMappingURL=claude.d.ts.map

package/dist/agents/claude.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA6CH,OAAO,EACL,KAAK,cAAc,EAEpB,MAAM,uBAAuB,CAAC;AAM/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG/D,eAAO,MAAM,yBAAyB,sBAAsB,CAAC;AAC7D,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAwJ1D;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,cAAc,CA0CvD;AA8RD,wBAAgB,MAAM,IAAI,eAAe,CAAC,QAAQ,CAAC,CAyDlD"}