@abelxiaoxing/cadence 1.0.3 → 1.0.4

package/config/.env.example

@@ -1,6 +1,21 @@
-# Copy to <project>/.pi/pi-abel-workflow/.env or ~/.pi/agent/pi-abel-workflow/.env.
+# Copy to <project>/.pi/cadence/.env or ~/.pi/agent/cadence/.env.
 # The project file wins as a whole file; values are not merged or interpolated.
 
+# Optional Subagent endpoint. Any non-empty key commits the whole layer, which
+# then requires MODEL and API_URL. Empty API/bounds use the documented defaults.
+SUBAGENT_API_URL=
+SUBAGENT_API_KEY=
+SUBAGENT_MODEL=
+# Dialect: openai-completions (default), openai-responses, anthropic-messages.
+SUBAGENT_API=
+# Internal defaults: context window 256000, max output tokens 128000.
+SUBAGENT_CONTEXT_WINDOW=
+SUBAGENT_MAX_TOKENS=
+
+# Per-role layers use the same six suffixes and override the global layer whole:
+# SUBAGENT_<ROLE>_<SUFFIX>, where ROLE is DESIGN_EXPLORER, CONTRACT_REVIEWER,
+# IMPLEMENTATION_WORKER, or DIAGNOSIS_WORKER. Partial/invalid layers fail closed.
+
 CONTEXT7_API_URL=https://context7.com/api/v2
 CONTEXT7_API_KEY=
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abelxiaoxing/cadence",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Prompts, skills, and a private orchestration extension exposing the Abel four-stage workflow (/abel-init, /abel-design, /abel-implement, /abel-diagnose) with package-owned professional Agents.",
   "license": "MIT",
   "type": "module",

package/skills/_shared/load-config.d.mts

@@ -0,0 +1,7 @@
+export declare function parseEnvFile(content: string): Record<string, string>;
+
+export declare function loadConfig(options: {
+  cwd: string;
+  home: string;
+  required?: readonly string[];
+}): { path: string; values: Record<string, string> };

package/src/contracts.ts

@@ -114,6 +114,7 @@ export const ENVIRONMENT_FAILURE_CODES = [
   "git-apply-unavailable",
   "git-ignore-check-failed",
   "git-index-unavailable",
+  "invalid-subagent-endpoint",
   "root-unavailable",
   "sandbox-runtime-unavailable",
 ] as const;
@@ -133,10 +134,16 @@ export type EnvironmentFailureCode = (typeof ENVIRONMENT_FAILURE_CODES)[number];
 export type ApprovalBoundaryCode = (typeof APPROVAL_BOUNDARY_CODES)[number];
 export type ChildTransportCode = (typeof CHILD_TRANSPORT_CODES)[number];
 
+export type EnvironmentFailure = {
+  kind: "environment";
+  code: EnvironmentFailureCode;
+  message?: string;
+};
+
 export type CandidateFailure =
   | { kind: "artifact"; code: ArtifactFailureCode; evidence?: string[] }
   | { kind: "stale"; code: StaleFailureCode }
-  | { kind: "environment"; code: EnvironmentFailureCode }
+  | EnvironmentFailure
   | { kind: "approval-boundary"; code: ApprovalBoundaryCode }
   | { kind: "cancelled"; code: "cancelled" }
   | { kind: "result-limit"; limitBytes: number };
@@ -163,7 +170,7 @@ export type TaskFailure =
       kind: "checkpoint-attempts-exhausted";
       cause: "artifact" | "stale";
     }
-  | { kind: "environment"; code: EnvironmentFailureCode }
+  | EnvironmentFailure
   | { kind: "result-limit"; limitBytes: number };
 
 export interface CandidateApplyEvidence {

package/src/parent-provider.ts

@@ -2,7 +2,13 @@ import {
   InMemoryCredentialStore,
   type Model,
   type Provider,
+  type StreamOptions,
 } from "@earendil-works/pi-ai";
+import {
+  createProvider,
+  stream as subagentStream,
+  streamSimple as subagentStreamSimple,
+} from "@earendil-works/pi-ai/compat";
 import {
   type ExtensionContext,
   ModelRuntime,
@@ -13,6 +19,117 @@ import type {
   ParentPayloadCallback,
   ParentPayloadCapture,
 } from "./parent-payload-bridge.ts";
+import type { SubagentEndpoint } from "./subagent-endpoint.ts";
+
+const SUBAGENT_PROVIDER_ID = "abel-subagent";
+
+function customStreamOptions<T extends StreamOptions>(
+  model: Model<string>,
+  options?: T,
+): T | undefined {
+  if (model.api !== "openai-responses") return options;
+  const childOnPayload = options?.onPayload;
+  return {
+    ...options,
+    onPayload: async (payload, requestModel) => {
+      const transformed = await childOnPayload?.(payload, requestModel);
+      const current = transformed === undefined ? payload : transformed;
+      if (!current || typeof current !== "object" || Array.isArray(current))
+        return current;
+      const normalized = { ...current } as Record<string, unknown>;
+      delete normalized.max_output_tokens;
+      return normalized;
+    },
+  } as T;
+}
+
+// The compat dispatchers resolve the concrete API implementation from
+// model.api at call time, so one pair serves all supported dialects.
+const SUBAGENT_STREAMS = {
+  stream(
+    model: Parameters<typeof subagentStream>[0],
+    context: Parameters<typeof subagentStream>[1],
+    options?: Parameters<typeof subagentStream>[2],
+  ) {
+    return subagentStream(
+      model,
+      context,
+      customStreamOptions(model as Model<string>, options),
+    );
+  },
+  streamSimple(
+    model: Parameters<typeof subagentStreamSimple>[0],
+    context: Parameters<typeof subagentStreamSimple>[1],
+    options?: Parameters<typeof subagentStreamSimple>[2],
+  ) {
+    return subagentStreamSimple(
+      model,
+      context,
+      customStreamOptions(model as Model<string>, options),
+    );
+  },
+};
+
+function customSubagentModel(endpoint: SubagentEndpoint): Model<string> {
+  return {
+    id: endpoint.model,
+    name: endpoint.model,
+    api: endpoint.dialect,
+    provider: SUBAGENT_PROVIDER_ID,
+    baseUrl: endpoint.url,
+    reasoning: true,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    contextWindow: endpoint.contextWindow,
+    maxTokens: endpoint.maxTokens,
+  } as Model<string>;
+}
+
+function customSubagentProvider(
+  endpoint: SubagentEndpoint,
+  model: Model<string>,
+): Provider {
+  return createProvider({
+    id: SUBAGENT_PROVIDER_ID,
+    name: "Abel Subagent Endpoint",
+    baseUrl: endpoint.url,
+    auth: {
+      apiKey: {
+        name: "Abel subagent endpoint auth",
+        resolve: async () =>
+          endpoint.apiKey
+            ? { auth: { apiKey: endpoint.apiKey }, source: "subagent-endpoint" }
+            : {
+                auth: {
+                  apiKey: "unused",
+                  headers: { authorization: null, "x-api-key": null },
+                },
+                source: "subagent-endpoint-keyless",
+              },
+      },
+    },
+    models: [model],
+    api: SUBAGENT_STREAMS,
+  }) as Provider;
+}
+
+export async function customPhaseRuntime(
+  endpoint: SubagentEndpoint,
+  signal?: AbortSignal,
+): Promise<PhaseRuntimeResult> {
+  if (signal?.aborted) return cancelledPhaseRuntime();
+  const model = customSubagentModel(endpoint);
+  const provider = customSubagentProvider(endpoint, model);
+  let modelRuntime: ModelRuntime;
+  try {
+    modelRuntime = await runtimeForProvider(provider, signal);
+  } catch (error) {
+    if (isCancellation(error, signal)) return cancelledPhaseRuntime();
+    throw error;
+  }
+  if (signal?.aborted) return cancelledPhaseRuntime();
+  return { ok: true, modelRuntime, model };
+}
 
 export interface PhasePayloadBridge {
   readonly bridge: ParentPayloadBridge;

package/src/runtime.ts

@@ -42,7 +42,7 @@ import {
   snapshotFiles,
 } from "./file-snapshot.ts";
 import type { ParentPayloadBridge } from "./parent-payload-bridge.ts";
-import { runtimeFromContext } from "./parent-provider.ts";
+import { customPhaseRuntime, runtimeFromContext } from "./parent-provider.ts";
 import { applyAgentsCheckpoint, applyRetainedPatch } from "./patch.ts";
 import {
   type BoundRetainedResult,
@@ -51,6 +51,11 @@ import {
   type RetainedCandidateIdentity,
 } from "./result-store.ts";
 import { declarationsConflict, Scheduler } from "./scheduler.ts";
+import {
+  describeInvalidSubagentEndpoint,
+  resolveSubagentEndpoint,
+  type SubagentEndpoint,
+} from "./subagent-endpoint.ts";
 import {
   type TaskRecord,
   taskConflictOf,
@@ -1309,11 +1314,30 @@ export class Runtime {
         ...cancellationError(signal),
         failureKind: "cancelled",
       };
-    const phase = await runtimeFromContext(
-      ctx,
-      this.parentPayloadBridge,
-      signal,
-    );
+    const task = this.taskRecords.get(envelope);
+    const endpoint = task
+      ? task.subagentEndpoint === null
+        ? ({ kind: "inherited" } as const)
+        : ({ kind: "custom", endpoint: task.subagentEndpoint } as const)
+      : resolveSubagentEndpoint(envelope.role, { cwd: ctx.cwd });
+    if (endpoint.kind === "invalid") {
+      const message = describeInvalidSubagentEndpoint(endpoint);
+      return {
+        ok: false,
+        error: message,
+        failure: {
+          kind: "environment",
+          code: "invalid-subagent-endpoint",
+          message,
+        },
+        failureKind: "failed",
+        failureClass: "environment",
+      };
+    }
+    const phase =
+      endpoint.kind === "custom"
+        ? await customPhaseRuntime(endpoint.endpoint, signal)
+        : await runtimeFromContext(ctx, this.parentPayloadBridge, signal);
     if (!phase.ok) {
       return {
         ok: false,
@@ -1425,7 +1449,6 @@ export class Runtime {
         usage: child.usage,
       };
     }
-    const task = this.taskRecords.get(envelope);
     const retainedRoot = task?.workspaceRoot ?? ctx.cwd;
     const retainedSnapshot =
       prepared?.snapshot ??
@@ -1547,11 +1570,43 @@ export class Runtime {
       const identity = workerIdentity(ctx.model);
       let record: TaskRecord;
       if (runRequest.kind === "open-task") {
+        const endpoint = resolveSubagentEndpoint("implementation-worker", {
+          cwd: ctx.cwd,
+        });
+        if (endpoint.kind === "invalid") {
+          const failure = {
+            kind: "environment",
+            code: "invalid-subagent-endpoint",
+            message: describeInvalidSubagentEndpoint(endpoint),
+          } as const;
+          record = this.registry.open(
+            runRequest.boundary,
+            identity,
+            workspaceRoot,
+            attempt,
+          );
+          record.state = {
+            kind: "blocked",
+            phase: attempt.phase,
+            failure,
+          };
+          return blockedOutcome(
+            {
+              taskId: attempt.taskId,
+              requestId: attempt.requestId,
+              phase: attempt.phase,
+            },
+            failure,
+          );
+        }
+        const subagentEndpoint: Readonly<SubagentEndpoint> | null =
+          endpoint.kind === "custom" ? endpoint.endpoint : null;
         record = this.registry.open(
           runRequest.boundary,
           identity,
           workspaceRoot,
           attempt,
+          subagentEndpoint,
         );
       } else {
         const existing = this.registry.get(key);

package/src/subagent-endpoint.ts

@@ -0,0 +1,158 @@
+// Per-role subagent endpoint resolution from the cadence env file.
+// Three-tier whole-layer semantics: role layer, global layer, inherited.
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { parseEnvFile } from "../skills/_shared/load-config.mjs";
+import { ROLES } from "./contracts.ts";
+
+export type SubagentRole = (typeof ROLES)[number];
+
+export type SubagentDialect =
+  | "openai-completions"
+  | "openai-responses"
+  | "anthropic-messages";
+
+const LAYER_FIELDS = [
+  "API_URL",
+  "API_KEY",
+  "MODEL",
+  "API",
+  "CONTEXT_WINDOW",
+  "MAX_TOKENS",
+] as const;
+type LayerField = (typeof LAYER_FIELDS)[number];
+type Layer = Partial<Record<LayerField, string>>;
+
+const GLOBAL_PREFIX = "SUBAGENT_";
+const DEFAULT_DIALECT: SubagentDialect = "openai-completions";
+const DIALECTS: readonly SubagentDialect[] = [
+  "openai-completions",
+  "openai-responses",
+  "anthropic-messages",
+];
+
+export const DEFAULT_CONTEXT_WINDOW = 256000;
+export const DEFAULT_MAX_TOKENS = 128000;
+
+export interface SubagentEndpoint {
+  readonly url: string;
+  readonly apiKey?: string;
+  readonly model: string;
+  readonly dialect: SubagentDialect;
+  readonly contextWindow: number;
+  readonly maxTokens: number;
+}
+
+export type SubagentEndpointResolution =
+  | { kind: "inherited" }
+  | { kind: "custom"; endpoint: Readonly<SubagentEndpoint> }
+  | { kind: "invalid"; keys: string[]; file?: string };
+
+export function describeInvalidSubagentEndpoint(
+  resolution: Extract<SubagentEndpointResolution, { kind: "invalid" }>,
+): string {
+  return resolution.keys.length > 0
+    ? `invalid subagent endpoint configuration keys: ${resolution.keys.join(", ")}`
+    : `invalid subagent endpoint configuration file: ${resolution.file ?? "unknown"}`;
+}
+
+function layerOf(values: Record<string, string>, prefix: string): Layer {
+  const layer: Layer = {};
+  for (const field of LAYER_FIELDS) {
+    const value = values[prefix + field];
+    if (value !== undefined && value !== "") layer[field] = value;
+  }
+  return layer;
+}
+
+function isCommitted(layer: Layer): boolean {
+  return LAYER_FIELDS.some((field) => layer[field] !== undefined);
+}
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function isPositiveInteger(value: string): boolean {
+  const number = Number(value);
+  return /^[0-9]+$/.test(value) && Number.isSafeInteger(number) && number > 0;
+}
+
+function offendingKeys(prefix: string, layer: Layer): string[] {
+  const keys: string[] = [];
+  if (layer.API_URL === undefined || !isHttpUrl(layer.API_URL))
+    keys.push(`${prefix}API_URL`);
+  if (layer.MODEL === undefined) keys.push(`${prefix}MODEL`);
+  if (
+    layer.API !== undefined &&
+    !DIALECTS.includes(layer.API as SubagentDialect)
+  )
+    keys.push(`${prefix}API`);
+  if (
+    layer.CONTEXT_WINDOW !== undefined &&
+    !isPositiveInteger(layer.CONTEXT_WINDOW)
+  )
+    keys.push(`${prefix}CONTEXT_WINDOW`);
+  if (layer.MAX_TOKENS !== undefined && !isPositiveInteger(layer.MAX_TOKENS))
+    keys.push(`${prefix}MAX_TOKENS`);
+  return keys;
+}
+
+function selectEnvFile(cwd: string, home: string): string | null {
+  const projectPath = path.join(cwd, ".pi", "cadence", ".env");
+  if (existsSync(projectPath)) return projectPath;
+  const userPath = path.join(home, ".pi", "agent", "cadence", ".env");
+  if (existsSync(userPath)) return userPath;
+  return null;
+}
+
+export function resolveSubagentEndpoint(
+  role: string,
+  options?: { cwd?: string; home?: string },
+): SubagentEndpointResolution {
+  if (!(ROLES as readonly string[]).includes(role))
+    return { kind: "invalid", keys: ["SUBAGENT_ROLE"] };
+  const cwd = options?.cwd ?? process.cwd();
+  const home = options?.home ?? homedir();
+  const file = selectEnvFile(cwd, home);
+  if (!file) return { kind: "inherited" };
+  let values: Record<string, string>;
+  try {
+    values = parseEnvFile(readFileSync(file, "utf8"));
+  } catch {
+    return { kind: "invalid", keys: [], file };
+  }
+  const rolePrefix = `SUBAGENT_${role.toUpperCase().replaceAll("-", "_")}_`;
+  const roleLayer = layerOf(values, rolePrefix);
+  let layer: Layer | undefined = isCommitted(roleLayer) ? roleLayer : undefined;
+  if (!layer) {
+    const globalLayer = layerOf(values, GLOBAL_PREFIX);
+    if (isCommitted(globalLayer)) layer = globalLayer;
+  }
+  if (!layer) return { kind: "inherited" };
+  const prefix = layer === roleLayer ? rolePrefix : GLOBAL_PREFIX;
+  const keys = offendingKeys(prefix, layer);
+  if (keys.length > 0) return { kind: "invalid", keys, file };
+  const endpoint: Readonly<SubagentEndpoint> = Object.freeze({
+    url: layer.API_URL ?? "",
+    ...(layer.API_KEY === undefined ? {} : { apiKey: layer.API_KEY }),
+    model: layer.MODEL ?? "",
+    dialect: (layer.API as SubagentDialect | undefined) ?? DEFAULT_DIALECT,
+    contextWindow:
+      layer.CONTEXT_WINDOW === undefined
+        ? DEFAULT_CONTEXT_WINDOW
+        : Number(layer.CONTEXT_WINDOW),
+    maxTokens:
+      layer.MAX_TOKENS === undefined
+        ? DEFAULT_MAX_TOKENS
+        : Number(layer.MAX_TOKENS),
+  });
+  return { kind: "custom", endpoint };
+}

package/src/worker.ts

@@ -8,6 +8,7 @@ import type {
   TaskFailure,
 } from "./contracts.ts";
 import type { ConflictDeclaration } from "./scheduler.ts";
+import type { SubagentEndpoint } from "./subagent-endpoint.ts";
 
 export type TaskState =
   | {
@@ -35,6 +36,7 @@ export interface TaskRecord {
   key: string;
   workspaceRoot: string;
   workerIdentity: string;
+  subagentEndpoint: Readonly<SubagentEndpoint> | null;
   boundary: TaskBoundary;
   conflict: ConflictDeclaration;
   state: TaskState;
@@ -118,6 +120,7 @@ export class WorkerRegistry {
     identity: string,
     workspaceRoot: string,
     attempt: PhaseAttempt,
+    subagentEndpoint: Readonly<SubagentEndpoint> | null = null,
   ): TaskRecord {
     const key = taskRecordKey(
       workspaceRoot,
@@ -130,6 +133,10 @@ export class WorkerRegistry {
       key,
       workspaceRoot,
       workerIdentity: identity,
+      subagentEndpoint:
+        subagentEndpoint === null
+          ? null
+          : Object.freeze({ ...subagentEndpoint }),
       boundary: storedBoundary,
       conflict: taskConflictOf(storedBoundary),
       state: { kind: "ready", phase: attempt.phase, launchIndex: 0 },