@homeostat/core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# @homeostat/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The library behind [homeostat](https://www.npmjs.com/package/homeostat): the entry and config schemas, validation, scoring, selection, the secret and risky-content scanners, the curator and deep dive, and the GitHub and Bitbucket providers.
+
+Most people want the `homeostat` command instead. This package is published for it and for tools built on the same knowledge-base format; its API follows the CLI's version and may change before 1.0.
+
+Apache-2.0. Source: <https://github.com/ysugarmen/homeostat>.

package/dist/src/automerge.d.ts

@@ -0,0 +1,27 @@
+import type { Config } from "./config.ts";
+import type { Frontmatter } from "./schema.ts";
+/** What the auto-merge gates look at: an entry plus its risky-content findings. */
+export interface MergeCandidate {
+    frontmatter: Frontmatter;
+    risks: readonly string[];
+}
+export type AutoMergeDecision = {
+    auto: true;
+} | {
+    auto: false;
+    reason: string;
+};
+/**
+ * Whether one entry may merge without a reviewer (security plan T1). The score says a lesson is
+ * genuine (a member's review comment led to a code change); the other gates check what the rule
+ * says and who wrote it. Any failed gate sends the entry to a human.
+ */
+export declare function autoMergeDecision(c: MergeCandidate, config: Config): AutoMergeDecision;
+/** Splits a run's entries into those that auto-merge (at most `maxPerRun`) and the rest. */
+export declare function splitAutoMerge<T extends MergeCandidate>(entries: readonly T[], config: Config): {
+    auto: T[];
+    review: {
+        entry: T;
+        reason: string;
+    }[];
+};

package/dist/src/automerge.js

@@ -0,0 +1,51 @@
+/**
+ * Whether one entry may merge without a reviewer (security plan T1). The score says a lesson is
+ * genuine (a member's review comment led to a code change); the other gates check what the rule
+ * says and who wrote it. Any failed gate sends the entry to a human.
+ */
+export function autoMergeDecision(c, config) {
+    const gate = config.scoring.autoMerge;
+    const fm = c.frontmatter;
+    const no = (reason) => ({ auto: false, reason });
+    if (!gate.enabled)
+        return no("auto-merge is off");
+    if (fm.status !== "accepted" || fm.score < config.scoring.autoMergeThreshold) {
+        return no(`score ${fm.score} is below the threshold (${config.scoring.autoMergeThreshold})`);
+    }
+    if (fm.source.type !== "pr-feedback")
+        return no("only review feedback from a member auto-merges");
+    if (fm.source.changedCode !== true)
+        return no("no code change followed the comment");
+    if (!config.team.members.some((m) => m.id === fm.source.author)) {
+        return no(`${fm.source.author} is not a team member`);
+    }
+    if (c.risks.length > 0)
+        return no("flagged by the risky-content check");
+    if (fm.flags?.length)
+        return no("flagged by a member");
+    if (gate.excludeAreas.includes(fm.area))
+        return no(`area ${fm.area} always needs a reviewer`);
+    if (gate.areas.length > 0 && !gate.areas.includes(fm.area)) {
+        return no(`area ${fm.area} is not in scoring.autoMerge.areas`);
+    }
+    return { auto: true };
+}
+/** Splits a run's entries into those that auto-merge (at most `maxPerRun`) and the rest. */
+export function splitAutoMerge(entries, config) {
+    const auto = [];
+    const review = [];
+    for (const entry of entries) {
+        const d = autoMergeDecision(entry, config);
+        if (!d.auto)
+            review.push({ entry, reason: d.reason });
+        else if (auto.length >= config.scoring.autoMerge.maxPerRun) {
+            review.push({
+                entry,
+                reason: `over the per-run cap (${config.scoring.autoMerge.maxPerRun})`,
+            });
+        }
+        else
+            auto.push(entry);
+    }
+    return { auto, review };
+}

package/dist/src/body.d.ts

@@ -0,0 +1,16 @@
+import { type Issue } from "./issues.ts";
+export declare const RULE_MAX_WORDS = 60;
+export declare const WHY_MAX_WORDS = 100;
+export interface BodySections {
+    rule?: string;
+    why?: string;
+    example?: string;
+}
+/**
+ * Splits an entry body into its fixed `## Rule`, `## Why` and `## Example` sections and checks
+ * the structural rules. Headings inside fenced code blocks are content, not sections.
+ */
+export declare function parseBody(body: string): {
+    sections: BodySections;
+    issues: Issue[];
+};

package/dist/src/body.js

@@ -0,0 +1,74 @@
+import { error } from "./issues.js";
+export const RULE_MAX_WORDS = 60;
+export const WHY_MAX_WORDS = 100;
+const SECTIONS = { rule: "Rule", why: "Why", example: "Example" };
+const isSectionKey = (name) => Object.hasOwn(SECTIONS, name);
+const countWords = (text) => text.split(/\s+/).filter(Boolean).length;
+/**
+ * Splits an entry body into its fixed `## Rule`, `## Why` and `## Example` sections and checks
+ * the structural rules. Headings inside fenced code blocks are content, not sections.
+ */
+export function parseBody(body) {
+    const issues = [];
+    const raw = {};
+    const preamble = [];
+    let current;
+    let fence;
+    for (const line of body.split(/\r?\n/)) {
+        const fenceMatch = /^\s*(```|~~~)/.exec(line);
+        if (fenceMatch) {
+            if (!fence)
+                fence = fenceMatch[1];
+            else if (line.trim().startsWith(fence))
+                fence = undefined;
+        }
+        const heading = fence || fenceMatch ? undefined : /^##\s+(.+?)\s*#*\s*$/.exec(line);
+        if (!heading?.[1]) {
+            (current ?? preamble).push(line);
+            continue;
+        }
+        const name = heading[1].toLowerCase();
+        if (!isSectionKey(name)) {
+            issues.push(error("body.section.unknown", `unknown section "## ${heading[1]}"; allowed: Rule, Why, Example`));
+            current = [];
+        }
+        else if (raw[name]) {
+            issues.push(error("body.section.duplicate", `section "## ${SECTIONS[name]}" appears twice`));
+            current = [];
+        }
+        else {
+            current = raw[name] = [];
+        }
+    }
+    if (preamble.join("").trim()) {
+        issues.unshift(error("body.preamble", "text before the first section; start the body with ## Rule"));
+    }
+    const sections = {};
+    for (const key of Object.keys(SECTIONS)) {
+        const text = raw[key]?.join("\n").trim();
+        if (text)
+            sections[key] = text;
+    }
+    if (!sections.rule) {
+        issues.push(error("body.rule.missing", "missing or empty ## Rule section"));
+    }
+    else {
+        if (/\n\s*\n/.test(sections.rule)) {
+            issues.push(error("body.rule.multiParagraph", "## Rule must be a single paragraph"));
+        }
+        const n = countWords(sections.rule);
+        if (n > RULE_MAX_WORDS) {
+            issues.push(error("body.rule.tooLong", `## Rule has ${n} words; max ${RULE_MAX_WORDS}`));
+        }
+    }
+    if (!sections.why) {
+        issues.push(error("body.why.missing", "missing or empty ## Why section"));
+    }
+    else {
+        const n = countWords(sections.why);
+        if (n > WHY_MAX_WORDS) {
+            issues.push(error("body.why.tooLong", `## Why has ${n} words; max ${WHY_MAX_WORDS}`));
+        }
+    }
+    return { sections, issues };
+}

package/dist/src/check.d.ts

@@ -0,0 +1,17 @@
+import type { Entry } from "./entry.ts";
+import { type Issue } from "./issues.ts";
+/** The `core` area always exists and holds team-wide entries. */
+export declare const CORE_AREA = "core";
+export interface CheckContext {
+    /** Path of the entry file relative to the KB root, e.g. `knowledge/core/my-rule.md`. */
+    path: string;
+    /** Area names from the config's `areas` key. */
+    areas: readonly string[];
+    autoMergeThreshold: number;
+    /** Member ids from the config's `team`. When omitted, member references are not checked. */
+    members?: readonly string[];
+    /** The computed score, when known; the threshold check uses it instead of the stored one. */
+    score?: number;
+}
+/** Checks one parsed entry against its location and the KB config. Pure; no I/O. */
+export declare function checkEntry(entry: Entry, ctx: CheckContext): Issue[];

package/dist/src/check.js

@@ -0,0 +1,56 @@
+import { error } from "./issues.js";
+import { countTokens } from "./tokens.js";
+/** The `core` area always exists and holds team-wide entries. */
+export const CORE_AREA = "core";
+/** Checks one parsed entry against its location and the KB config. Pure; no I/O. */
+export function checkEntry(entry, ctx) {
+    const fm = entry.frontmatter;
+    const file = ctx.path;
+    const issues = [];
+    const parts = ctx.path.replaceAll("\\", "/").split("/");
+    const filename = parts.at(-1) ?? "";
+    if (filename !== `${fm.id}.md`) {
+        issues.push(error("path.filename", `filename must be "${fm.id}.md" to match id`, { path: "id", file }));
+    }
+    if (parts.length !== 3 || parts[0] !== "knowledge") {
+        issues.push(error("path.root", `entry must live at knowledge/<area>/${fm.id}.md`, { file }));
+    }
+    else if (parts[1] !== fm.area) {
+        issues.push(error("path.folder", `folder "${parts[1]}" does not match area "${fm.area}"`, {
+            path: "area",
+            file,
+        }));
+    }
+    if (fm.area !== CORE_AREA && !ctx.areas.includes(fm.area)) {
+        issues.push(error("area.unknown", `area "${fm.area}" is not in the config's areas (${[CORE_AREA, ...ctx.areas].join(", ")})`, { path: "area", file }));
+    }
+    if (ctx.members) {
+        const refs = [
+            ["owner", fm.owner],
+            ["source.author", fm.source.author],
+            ["approvedBy", fm.approvedBy],
+            ...(fm.flags ?? []).map((f, i) => [`flags.${i}.by`, f.by]),
+        ];
+        for (const [path, member] of refs) {
+            if (member !== undefined && !ctx.members.includes(member)) {
+                issues.push(error("member.unknown", `${path}: "${member}" is not a team member`, { path, file }));
+            }
+        }
+    }
+    const score = ctx.score ?? fm.score;
+    if (fm.status === "accepted" && score < ctx.autoMergeThreshold && !fm.approvedBy) {
+        issues.push(error("accepted.belowThreshold", `accepted with score ${score} below the auto-merge threshold ${ctx.autoMergeThreshold}; set approvedBy or lower the status`, { path: "status", file }));
+    }
+    const tokens = countTokens(entry.body);
+    if (fm.tokens !== tokens) {
+        issues.push({
+            code: "tokens.mismatch",
+            severity: "warning",
+            message: `tokens is ${fm.tokens}, body counts ${tokens}; run with --fix to update`,
+            path: "tokens",
+            file,
+            fix: { field: "tokens", value: tokens },
+        });
+    }
+    return issues;
+}

package/dist/src/claude-code.d.ts

@@ -0,0 +1,36 @@
+import { type Asker, type Effort } from "./claude.ts";
+export interface RunResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** Runs a command with `input` on stdin; rejects with an ENOENT error when it is not installed. */
+export type CommandRunner = (command: string, args: readonly string[], input: string, env: NodeJS.ProcessEnv) => Promise<RunResult>;
+export interface ClaudeCodeAskerOptions {
+    model: string;
+    effort: Effort;
+    /** The Claude Code binary; defaults to `claude` on the PATH. */
+    command?: string;
+    /** Injected for tests. */
+    run?: CommandRunner;
+    env?: NodeJS.ProcessEnv;
+}
+/** Set on the child so the homeostat plugin's own hooks never fire inside an agent call. */
+export declare const AGENT_ENV = "HOMEOSTAT_AGENT";
+/**
+ * Flags for a bare structured call: our system prompt instead of Claude Code's, no tools, no MCP
+ * servers, no skills, no user/project settings (so no plugins or hooks). That keeps a call at
+ * about a thousand input tokens instead of the full interactive context.
+ */
+export declare function claudeCodeArgs(opts: {
+    model: string;
+    effort: Effort;
+}, system: string, jsonSchema: object): string[];
+/**
+ * The Claude Code runtime: runs `claude -p`, which uses whatever Claude Code is logged in with:
+ * an interactive login, a `claude setup-token` token as CLAUDE_CODE_OAUTH_TOKEN, or an API key.
+ * Anthropic's terms limit a personal Free/Pro/Max subscription to the subscriber's own,
+ * non-commercial use and forbid sharing its token, so a team KB should use the API runtime or a
+ * Team/Enterprise plan instead (see docs/execution-plan.md, decisions log).
+ */
+export declare function claudeCodeAsker(opts: ClaudeCodeAskerOptions): Asker;

package/dist/src/claude-code.js

@@ -0,0 +1,100 @@
+import { spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+import { z } from "zod";
+import { ClaudeUnavailableError } from "./claude.js";
+const spawnRunner = (command, args, input, env) => new Promise((resolve, reject) => {
+    // Run outside any repo so no project CLAUDE.md or settings are picked up.
+    const child = spawn(command, [...args], {
+        cwd: tmpdir(),
+        env,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += d));
+    child.stderr.on("data", (d) => (stderr += d));
+    child.on("error", reject);
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+    child.stdin.on("error", () => { });
+    child.stdin.end(input);
+});
+/** Set on the child so the homeostat plugin's own hooks never fire inside an agent call. */
+export const AGENT_ENV = "HOMEOSTAT_AGENT";
+/**
+ * Flags for a bare structured call: our system prompt instead of Claude Code's, no tools, no MCP
+ * servers, no skills, no user/project settings (so no plugins or hooks). That keeps a call at
+ * about a thousand input tokens instead of the full interactive context.
+ */
+export function claudeCodeArgs(opts, system, jsonSchema) {
+    return [
+        "-p",
+        "--system-prompt",
+        system,
+        "--output-format",
+        "json",
+        "--json-schema",
+        JSON.stringify(jsonSchema),
+        "--tools",
+        "",
+        "--strict-mcp-config",
+        "--disable-slash-commands",
+        "--setting-sources",
+        "",
+        "--no-session-persistence",
+        "--model",
+        opts.model,
+        "--effort",
+        opts.effort,
+    ];
+}
+const resultSchema = z.object({
+    is_error: z.boolean().optional(),
+    subtype: z.string().optional(),
+    stop_reason: z.string().nullable().optional(),
+    result: z.string().optional(),
+    structured_output: z.unknown().optional(),
+});
+/**
+ * The Claude Code runtime: runs `claude -p`, which uses whatever Claude Code is logged in with:
+ * an interactive login, a `claude setup-token` token as CLAUDE_CODE_OAUTH_TOKEN, or an API key.
+ * Anthropic's terms limit a personal Free/Pro/Max subscription to the subscriber's own,
+ * non-commercial use and forbid sharing its token, so a team KB should use the API runtime or a
+ * Team/Enterprise plan instead (see docs/execution-plan.md, decisions log).
+ */
+export function claudeCodeAsker(opts) {
+    const run = opts.run ?? spawnRunner;
+    const command = opts.command ?? "claude";
+    return async (system, user, schema) => {
+        const { $schema: _, ...jsonSchema } = z.toJSONSchema(schema);
+        const args = claudeCodeArgs(opts, system, jsonSchema);
+        let out;
+        try {
+            out = await run(command, args, user, { ...(opts.env ?? process.env), [AGENT_ENV]: "1" });
+        }
+        catch (e) {
+            if (e.code === "ENOENT") {
+                throw new ClaudeUnavailableError(`Claude Code (${command}) is not installed: install it, or use agents.runtime: api`);
+            }
+            throw e;
+        }
+        let parsed;
+        try {
+            parsed = resultSchema.parse(JSON.parse(out.stdout));
+        }
+        catch {
+            const detail = (out.stderr || out.stdout).trim().split("\n").slice(-3).join(" ");
+            throw new ClaudeUnavailableError(`Claude Code failed (exit ${out.code}): ${detail}`);
+        }
+        if (parsed.is_error || parsed.subtype !== "success") {
+            const detail = parsed.result ?? parsed.subtype ?? "unknown error";
+            const login = /log ?in|auth|credential|token|api key/i.test(detail)
+                ? " (run `claude` to log in, or set CLAUDE_CODE_OAUTH_TOKEN from `claude setup-token`)"
+                : "";
+            throw new ClaudeUnavailableError(`Claude Code: ${detail}${login}`);
+        }
+        if (parsed.stop_reason === "refusal")
+            return null;
+        const value = schema.safeParse(parsed.structured_output);
+        return value.success ? value.data : null;
+    };
+}

package/dist/src/claude.d.ts

@@ -0,0 +1,29 @@
+import Anthropic from "@anthropic-ai/sdk";
+import type { z } from "zod";
+export type Effort = "low" | "medium" | "high" | "xhigh" | "max";
+/**
+ * One structured question to Claude: the reply is validated against `schema`. Null when Claude
+ * declines or the reply does not fit. Implemented by the API runtime and the Claude Code runtime.
+ */
+export type Asker = <S extends z.ZodType>(system: string, user: string, schema: S) => Promise<z.infer<S> | null>;
+/** Claude could not be reached or refused the credentials; the agent run cannot continue. */
+export declare class ClaudeUnavailableError extends Error {
+}
+/** The part of the Anthropic client the API runtime uses, so tests can pass a stub. */
+export type ClaudeClient = Pick<Anthropic, "beta">;
+export interface ApiAskerOptions {
+    model: string;
+    effort: Effort;
+    /** Defaults to a client built from `env`. */
+    client?: ClaudeClient;
+    /**
+     * Where to read ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN. When given, only these are used, so
+     * a caller's environment (or a test's empty one) is never bypassed. Defaults to the SDK's own.
+     */
+    env?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * The API runtime: the Messages API through @anthropic-ai/sdk, billed per use to a Claude
+ * Console key. Uses structured outputs and the server-side refusal fallback.
+ */
+export declare function apiAsker(opts: ApiAskerOptions): Asker;