clinkx 1.0.0 → 1.1.1

package/clinkx-workflows/dist/roster-contract.js

@@ -0,0 +1,180 @@
+/**
+ * Frozen wire shapes for roster presets, list_workflows capability
+ * advertisements, and resolved_roster projection. No behavior.
+ */
+import { z } from "zod";
+import { WorkflowDelegateSchema } from "./delegate-validate.js";
+import { EFFORT_VALUE_MAX, EFFORT_VALUE_PATTERN, MODEL_VALUE_MAX, MODEL_VALUE_PATTERN, } from "./schema.js";
+export const ROSTER_SCHEMA_VERSION = "clinkx-roster-v1";
+export const ROSTER_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+export const ROSTER_SOURCES = ["env", "user", "builtin"];
+export const ROSTER_MEMBERS_MIN = 1;
+export const ROSTER_MEMBERS_MAX = 10;
+export const ROSTER_STANCE_REQUIRED_FROM_INDEX = 3;
+export const ROSTER_STANCE_MAX_CHARS = 200;
+export const RosterNameSchema = z.string().regex(ROSTER_NAME_PATTERN);
+// Keep in sync with schema.ts MODEL/EFFORT patterns and
+// workflow-tools.ts MODEL_OVERRIDE_PATTERN / EFFORT_OVERRIDE_PATTERN.
+const RosterModelSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(MODEL_VALUE_MAX)
+    .regex(MODEL_VALUE_PATTERN);
+const RosterEffortSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(EFFORT_VALUE_MAX)
+    .regex(EFFORT_VALUE_PATTERN);
+const RosterCliNameSchema = z.string().trim().min(1);
+// Stance rules: parseMembersOverride in workflow-tools.ts (trim + collapse,
+// non-blank, no {{ / }}, 200-char ceiling after normalization).
+const RosterStanceSchema = z
+    .string()
+    .transform((value) => value.trim().replace(/\s+/g, " "))
+    .superRefine((collapsed, ctx) => {
+    if (collapsed === "") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "stance must not be blank",
+        });
+    }
+    if (collapsed.includes("{{") || collapsed.includes("}}")) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "stance must not contain {{ or }}",
+        });
+    }
+    if (collapsed.length > ROSTER_STANCE_MAX_CHARS) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `stance must be at most ${ROSTER_STANCE_MAX_CHARS} characters after normalization`,
+        });
+    }
+});
+export const AvailableCliCapabilitySchema = z
+    .object({
+    name: z.string().min(1),
+    supports_model: z.boolean(),
+    supports_effort: z.boolean(),
+    effort_allowed_values: z.array(z.string()),
+})
+    .strict();
+export const AvailableRosterSchema = z
+    .object({
+    name: RosterNameSchema,
+    source: z.enum(ROSTER_SOURCES),
+})
+    .strict();
+export const RosterPresetMemberSchema = z
+    .object({
+    cli_name: RosterCliNameSchema,
+    stance: RosterStanceSchema.optional(),
+    model: RosterModelSchema.optional(),
+    effort: RosterEffortSchema.optional(),
+})
+    .strict();
+export const RosterPresetMembersSchema = z
+    .array(RosterPresetMemberSchema)
+    .min(ROSTER_MEMBERS_MIN)
+    .max(ROSTER_MEMBERS_MAX)
+    .superRefine((members, ctx) => {
+    for (let index = ROSTER_STANCE_REQUIRED_FROM_INDEX; index < members.length; index++) {
+        if (members[index]?.stance === undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "stance is required for members at index 3 and above",
+                path: [index, "stance"],
+            });
+        }
+    }
+});
+export const RosterPresetChairmanSchema = z
+    .object({
+    cli_name: RosterCliNameSchema.optional(),
+    model: RosterModelSchema.optional(),
+    effort: RosterEffortSchema.optional(),
+})
+    .strict();
+// Enabled-delegate shape from delegate-validate.ts (EnabledDelegateSchema).
+// Unwrap the cb_delegate default so an omitted preset delegate stays omitted.
+export const RosterPresetDelegateSchema = WorkflowDelegateSchema.removeDefault().superRefine((delegate, ctx) => {
+    if (delegate.enabled !== true) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "roster delegate must be the enabled-delegate shape",
+        });
+    }
+});
+export const RosterPresetSchema = z
+    .object({
+    schema_version: z.literal(ROSTER_SCHEMA_VERSION),
+    description: z.string().optional(),
+    members: RosterPresetMembersSchema.optional(),
+    chairman: RosterPresetChairmanSchema.optional(),
+    delegate: RosterPresetDelegateSchema.optional(),
+})
+    .strict()
+    .superRefine((preset, ctx) => {
+    if (preset.members === undefined &&
+        preset.chairman === undefined &&
+        preset.delegate === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "roster preset requires at least one of members, chairman, or delegate",
+        });
+    }
+});
+export const ResolvedRosterSeatSchema = z
+    .object({
+    index: z.number().int().min(0).max(ROSTER_MEMBERS_MAX - 1),
+    cli_name: RosterCliNameSchema,
+    model: RosterModelSchema.optional(),
+    effort: RosterEffortSchema.optional(),
+    stance_present: z.boolean(),
+})
+    .strict();
+export const ResolvedRosterChairmanSchema = z
+    .object({
+    cli_name: RosterCliNameSchema.optional(),
+    model: RosterModelSchema.optional(),
+    effort: RosterEffortSchema.optional(),
+})
+    .strict();
+const ResolvedRosterProviderSchema = z
+    .object({
+    cli_name: RosterCliNameSchema,
+    role: z.string().trim().min(1),
+    model: RosterModelSchema.optional(),
+    effort: RosterEffortSchema.optional(),
+})
+    .strict();
+export const ResolvedRosterDelegateSchema = z.union([
+    z
+        .object({
+        enabled: z.literal(true),
+        curator: ResolvedRosterProviderSchema,
+        finalizer: ResolvedRosterProviderSchema.extend({
+            effective_enabled: z.boolean(),
+        }).strict(),
+    })
+        .strict(),
+    z
+        .object({
+        enabled: z.literal(false),
+    })
+        .strict(),
+]);
+export const ResolvedRosterSchema = z
+    .object({
+    roster: RosterNameSchema.optional(),
+    members: z.array(ResolvedRosterSeatSchema),
+    reviewers: z.array(ResolvedRosterSeatSchema),
+    chairman: ResolvedRosterChairmanSchema,
+    delegate: ResolvedRosterDelegateSchema,
+    provider_spawns: z.number().int().min(0),
+    preflight_calls: z.number().int().min(0),
+})
+    .strict();
+//# sourceMappingURL=roster-contract.js.map

package/clinkx-workflows/dist/roster-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roster-contract.js","sourceRoot":"","sources":["../src/roster-contract.ts"],"names":[],"mappings":"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"}

package/clinkx-workflows/dist/rosters.d.ts

@@ -0,0 +1,14 @@
+import { logger as defaultLogger } from "./logger.js";
+import { type AvailableRoster, type RosterPreset } from "./roster-contract.js";
+export interface RosterLoaderOptions {
+    envPath?: string | undefined;
+    userDir?: string | undefined;
+    builtinDir?: string | undefined;
+    logger?: typeof defaultLogger | undefined;
+}
+export interface RosterLoader {
+    list(): AvailableRoster[];
+    load(name: string): RosterPreset | undefined;
+}
+export declare function resolveRosterLoaderOptionsFromEnv(env?: NodeJS.ProcessEnv): RosterLoaderOptions;
+export declare function createRosterLoader(options?: RosterLoaderOptions): RosterLoader;

package/clinkx-workflows/dist/rosters.js

@@ -0,0 +1,169 @@
+/**
+ * Roster preset discovery. Mirrors adapter-registry discipline in the root
+ * package (`src/registry.ts`): env path (file or directory) replaces the
+ * default locations; otherwise user XDG then an injected builtin directory.
+ * First-wins by name. Synchronous. No cache: list() and load() re-read the
+ * filesystem each call. Presets are tiny.
+ */
+import { lstatSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { logger as defaultLogger } from "./logger.js";
+import { ROSTER_NAME_PATTERN, RosterPresetSchema, } from "./roster-contract.js";
+function defaultUserDir(env = process.env) {
+    const xdg = env["XDG_CONFIG_HOME"];
+    const xdgHome = xdg != null && xdg !== "" ? xdg : join(homedir(), ".config");
+    return join(xdgHome, "clinkx", "rosters");
+}
+export function resolveRosterLoaderOptionsFromEnv(env = process.env) {
+    const envPath = env["CLINKX_ROSTERS_PATH"];
+    return {
+        ...(envPath != null && envPath !== "" ? { envPath } : {}),
+        userDir: defaultUserDir(env),
+    };
+}
+export function createRosterLoader(options = {}) {
+    const log = options.logger ?? defaultLogger;
+    const userDir = options.userDir ?? defaultUserDir();
+    const discover = () => {
+        const claims = new Map();
+        for (const spec of sourceSpecs(options.envPath, userDir, options.builtinDir)) {
+            ingestPath(spec, claims, log);
+        }
+        return claims;
+    };
+    return {
+        list() {
+            const available = [];
+            for (const [name, claim] of discover()) {
+                if (claim.state === "available") {
+                    available.push({ name, source: claim.source });
+                }
+            }
+            available.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+            return available;
+        },
+        load(name) {
+            if (!ROSTER_NAME_PATTERN.test(name)) {
+                return undefined;
+            }
+            const claim = discover().get(name);
+            return claim?.state === "available" ? claim.preset : undefined;
+        },
+    };
+}
+function sourceSpecs(envPath, userDir, builtinDir) {
+    if (envPath != null && envPath !== "") {
+        return [{ source: "env", path: envPath, allowFile: true }];
+    }
+    const specs = [];
+    if (userDir !== "") {
+        specs.push({ source: "user", path: userDir, allowFile: false });
+    }
+    if (builtinDir != null && builtinDir !== "") {
+        specs.push({ source: "builtin", path: builtinDir, allowFile: false });
+    }
+    return specs;
+}
+function ingestPath(spec, claims, log) {
+    const stats = lstatOrUndefined(spec.path);
+    if (stats === undefined) {
+        if (spec.source === "env") {
+            log.warn({ path: spec.path }, "CLINKX_ROSTERS_PATH not found");
+        }
+        return;
+    }
+    if (stats.isSymbolicLink()) {
+        log.warn({ path: spec.path }, "skipping symlinked roster path");
+        return;
+    }
+    if (stats.isDirectory()) {
+        ingestDir(spec.path, spec.source, claims, log);
+        return;
+    }
+    if (stats.isFile()) {
+        if (!spec.allowFile) {
+            log.warn({ path: spec.path, source: spec.source }, "roster location is not a directory");
+            return;
+        }
+        ingestFile(spec.path, spec.source, claims, log);
+        return;
+    }
+    log.warn({ path: spec.path }, "skipping unsupported roster path");
+}
+function ingestDir(dirPath, source, claims, log) {
+    let entries;
+    try {
+        entries = readdirSync(dirPath);
+    }
+    catch (err) {
+        log.warn({ path: dirPath, err }, "could not read roster directory");
+        return;
+    }
+    const files = entries.filter((entry) => entry.endsWith(".json")).sort();
+    for (const filename of files) {
+        ingestFile(join(dirPath, filename), source, claims, log);
+    }
+}
+function ingestFile(filePath, source, claims, log) {
+    const filename = basename(filePath);
+    if (!filename.endsWith(".json")) {
+        log.warn({ path: filePath }, "skipping roster file without .json suffix");
+        return;
+    }
+    const name = filename.slice(0, -".json".length);
+    if (!ROSTER_NAME_PATTERN.test(name)) {
+        log.warn({ path: filePath, name }, "skipping roster file with invalid name");
+        return;
+    }
+    if (claims.has(name)) {
+        return;
+    }
+    const stats = lstatOrUndefined(filePath);
+    if (stats === undefined) {
+        log.warn({ path: filePath, name }, "roster file not found");
+        return;
+    }
+    if (stats.isSymbolicLink()) {
+        log.warn({ path: filePath, name }, "skipping symlinked roster file");
+        return;
+    }
+    if (!stats.isFile()) {
+        log.warn({ path: filePath, name }, "skipping non-file roster path");
+        return;
+    }
+    let raw;
+    try {
+        raw = readFileSync(filePath, "utf-8");
+    }
+    catch (err) {
+        log.warn({ path: filePath, name, err }, "could not read roster file");
+        claims.set(name, { state: "unavailable" });
+        return;
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (err) {
+        log.warn({ path: filePath, name, err }, "skipping malformed roster preset");
+        claims.set(name, { state: "unavailable" });
+        return;
+    }
+    const parsed = RosterPresetSchema.safeParse(json);
+    if (!parsed.success) {
+        log.warn({ path: filePath, name, err: parsed.error.message }, "skipping invalid roster preset");
+        claims.set(name, { state: "unavailable" });
+        return;
+    }
+    claims.set(name, { state: "available", source, preset: parsed.data });
+}
+function lstatOrUndefined(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=rosters.js.map

package/clinkx-workflows/dist/rosters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rosters.js","sourceRoot":"","sources":["../src/rosters.ts"],"names":[],"mappings":"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"}

package/clinkx-workflows/dist/run-health.d.ts

@@ -0,0 +1,7 @@
+import type { ContextBuilderLifecycleStateV1 } from "./context-builder-lifecycle-contract.js";
+import type { RunState } from "./state-schema.js";
+/** Read-time diagnostics shared by status projection and age-based retention. */
+export declare function computeRunHealth(state: Pick<RunState, "status" | "stages" | "workflow_context">, lifecycle: ContextBuilderLifecycleStateV1 | undefined): {
+    classification: "degraded" | "ok";
+    reasons: string[];
+};

package/clinkx-workflows/dist/run-health.js

@@ -0,0 +1,25 @@
+import { isDelegateExternalGapDegrade } from "./delegate-signature.js";
+/** Read-time diagnostics shared by status projection and age-based retention. */
+export function computeRunHealth(state, lifecycle) {
+    const reasons = [];
+    if (state.status === "succeeded" && state.stages.some((stage) => stage.calls.some((call) => call.state === "failed"))) {
+        reasons.push("failed_calls_in_succeeded_run");
+    }
+    if (lifecycle?.status === "partial") {
+        reasons.push("context_partial");
+    }
+    if (lifecycle?.status === "failed") {
+        reasons.push("context_lifecycle_failed");
+    }
+    if (lifecycle?.coverage.status === "degraded") {
+        reasons.push("coverage_degraded");
+    }
+    if (state.workflow_context?.context_builder.delegate?.fallback_used === true) {
+        reasons.push("delegate_fallback_used");
+    }
+    if (isDelegateExternalGapDegrade(state.workflow_context?.context_builder.delegate)) {
+        reasons.push("context_external_gaps");
+    }
+    return { classification: reasons.length > 0 ? "degraded" : "ok", reasons };
+}
+//# sourceMappingURL=run-health.js.map

package/clinkx-workflows/dist/run-health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-health.js","sourceRoot":"","sources":["../src/run-health.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC;AAEvE,iFAAiF;AACjF,MAAM,UAAU,gBAAgB,CAC9B,KAA+D,EAC/D,SAAqD;IAErD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,CACnD,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAC/D,EAAE,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,SAAS,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;QACpC,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,SAAS,EAAE,MAAM,KAAK,QAAQ,EAAE,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,SAAS,EAAE,QAAQ,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QAC9C,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,KAAK,CAAC,gBAAgB,EAAE,eAAe,CAAC,QAAQ,EAAE,aAAa,KAAK,IAAI,EAAE,CAAC;QAC7E,OAAO,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;IACzC,CAAC;IACD,IAAI,4BAA4B,CAAC,KAAK,CAAC,gBAAgB,EAAE,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnF,OAAO,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC;AAC7E,CAAC"}