@workbench-ai/agent-driver 0.0.44

package/dist/access-contracts.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import type { GlobalSkillCatalog, GlobalSkillCatalogEntry, GlobalSkillProviderSupport, GlobalSkillUpdate, ProviderIntegrationCatalog, ProviderIntegrationCatalogEntry, ProviderIntegrationUpdate } from "./types.js";
+export declare const GlobalSkillProviderSupportSchema: z.ZodType<GlobalSkillProviderSupport>;
+export declare const GlobalSkillCatalogEntrySchema: z.ZodType<GlobalSkillCatalogEntry>;
+export declare const GlobalSkillCatalogSchema: z.ZodType<GlobalSkillCatalog>;
+export declare const GlobalSkillUpdateSchema: z.ZodType<GlobalSkillUpdate>;
+export declare const ProviderIntegrationCatalogEntrySchema: z.ZodType<ProviderIntegrationCatalogEntry>;
+export declare const ProviderIntegrationCatalogSchema: z.ZodType<ProviderIntegrationCatalog>;
+export declare const ProviderIntegrationUpdateSchema: z.ZodType<ProviderIntegrationUpdate>;
+//# sourceMappingURL=access-contracts.d.ts.map

package/dist/access-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-contracts.d.ts","sourceRoot":"","sources":["../src/access-contracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EACV,kBAAkB,EAClB,uBAAuB,EACvB,0BAA0B,EAC1B,iBAAiB,EACjB,0BAA0B,EAC1B,+BAA+B,EAC/B,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,gCAAgC,EAAE,CAAC,CAAC,OAAO,CAAC,0BAA0B,CAKxE,CAAC;AAEZ,eAAO,MAAM,6BAA6B,EAAE,CAAC,CAAC,OAAO,CAAC,uBAAuB,CAQlE,CAAC;AAEZ,eAAO,MAAM,wBAAwB,EAAE,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAIxD,CAAC;AAEZ,eAAO,MAAM,uBAAuB,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAItD,CAAC;AAEZ,eAAO,MAAM,qCAAqC,EAAE,CAAC,CAAC,OAAO,CAAC,+BAA+B,CAMlF,CAAC;AAEZ,eAAO,MAAM,gCAAgC,EAAE,CAAC,CAAC,OAAO,CAAC,0BAA0B,CAMxE,CAAC;AAEZ,eAAO,MAAM,+BAA+B,EAAE,CAAC,CAAC,OAAO,CAAC,yBAAyB,CAItE,CAAC"}

package/dist/access-contracts.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+export const GlobalSkillProviderSupportSchema = z
+    .object({
+    providerId: z.string().min(1),
+    providerLabel: z.string().min(1),
+})
+    .strict();
+export const GlobalSkillCatalogEntrySchema = z
+    .object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    summary: z.string().nullable(),
+    enabled: z.boolean(),
+    providerSupport: z.array(GlobalSkillProviderSupportSchema).default([]),
+})
+    .strict();
+export const GlobalSkillCatalogSchema = z
+    .object({
+    skills: z.array(GlobalSkillCatalogEntrySchema).default([]),
+})
+    .strict();
+export const GlobalSkillUpdateSchema = z
+    .object({
+    enabled: z.boolean(),
+})
+    .strict();
+export const ProviderIntegrationCatalogEntrySchema = z
+    .object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    enabled: z.boolean(),
+})
+    .strict();
+export const ProviderIntegrationCatalogSchema = z
+    .object({
+    providerId: z.string().min(1),
+    providerLabel: z.string().min(1),
+    integrations: z.array(ProviderIntegrationCatalogEntrySchema).default([]),
+})
+    .strict();
+export const ProviderIntegrationUpdateSchema = z
+    .object({
+    enabledIds: z.array(z.string().min(1)),
+})
+    .strict();

package/dist/behavior-contract.d.ts

@@ -0,0 +1,26 @@
+import type { JsonValue } from "./types.js";
+import type { ActiveHarnessSession, HarnessExecutionPlan, HarnessProvider, HarnessSessionMode } from "./index.js";
+type BehaviorIssueHookResult = Promise<string[] | void> | string[] | void;
+export interface HarnessBehaviorContractArgs {
+    provider: HarnessProvider<unknown>;
+    repoRoot: string;
+    runtimeHome: string;
+    executionId: string;
+    ownerId: string;
+    workspacePath: string;
+    stageSessionPath: string;
+    prompt: string;
+    attemptNumber?: number;
+    stageId?: string;
+    stageRunIndex?: number;
+    ownerStageId?: string;
+    sessionMode?: HarnessSessionMode;
+    persistedSession?: Record<string, JsonValue> | null;
+    plan?: HarnessExecutionPlan;
+    exerciseReadiness?: boolean;
+    exerciseStartSession?: boolean;
+    validateSession?: (session: ActiveHarnessSession<unknown>) => BehaviorIssueHookResult;
+}
+export declare function collectHarnessProviderBehaviorContractIssues(args: HarnessBehaviorContractArgs): Promise<string[]>;
+export {};
+//# sourceMappingURL=behavior-contract.d.ts.map

package/dist/behavior-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"behavior-contract.d.ts","sourceRoot":"","sources":["../src/behavior-contract.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,KAAK,EACV,oBAAoB,EAEpB,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAEnB,MAAM,YAAY,CAAC;AAEpB,KAAK,uBAAuB,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;AAE1E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,IAAI,CAAC;IACpD,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC,KAAK,uBAAuB,CAAC;CACvF;AAYD,wBAAsB,4CAA4C,CAAC,IAAI,EAAE,2BAA2B,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAoCvH"}

package/dist/behavior-contract.js

@@ -0,0 +1,200 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { collectHarnessProviderConformanceIssues } from "./conformance.js";
+export async function collectHarnessProviderBehaviorContractIssues(args) {
+    const context = createContractContext(args);
+    const issues = collectHarnessProviderConformanceIssues(args.provider);
+    await Promise.all([args.repoRoot, args.runtimeHome, args.workspacePath, args.stageSessionPath].map(ensureDir));
+    await seedDefaultSecretRefEnv(context.plan, args.repoRoot);
+    if (args.exerciseReadiness ?? true) {
+        await maybeExerciseReadiness(args, context.plan, issues);
+    }
+    const adapter = createAdapter(args.provider, issues);
+    if (!adapter) {
+        return issues;
+    }
+    validateAdapterBasics(args.provider, adapter, context.plan, issues);
+    const sessionBaseArgs = createSessionBaseArgs(args, context);
+    if (args.exerciseStartSession ?? true) {
+        const session = await captureAsyncIssue(issues, "startSession", () => adapter.startSession({ ...sessionBaseArgs, sessionMode: context.sessionMode }));
+        if (session) {
+            try {
+                validateStartedSession(session, args.provider.manifest.id, context, issues);
+                await pushHookIssues(issues, args.validateSession?.(session));
+            }
+            finally {
+                await captureAsyncIssue(issues, "closeSession threw after contract startSession check", () => adapter.closeSession(session, context.plan.harness.cancel));
+            }
+        }
+    }
+    return issues;
+}
+function createContractContext(args) {
+    const stageId = args.stageId ?? "stage";
+    return {
+        plan: args.plan ?? createDefaultBehaviorPlan(args.provider),
+        attemptNumber: args.attemptNumber ?? 1,
+        stageId,
+        stageRunIndex: args.stageRunIndex ?? 0,
+        ownerStageId: args.ownerStageId ?? stageId,
+        sessionMode: args.sessionMode ?? "fresh",
+        persistedSession: args.persistedSession ?? null,
+    };
+}
+function createSessionBaseArgs(args, context) {
+    return {
+        repoRoot: args.repoRoot,
+        runtimeHome: args.runtimeHome,
+        plan: context.plan,
+        ownerId: args.ownerId,
+        executionId: args.executionId,
+        attemptNumber: context.attemptNumber,
+        stageId: context.stageId,
+        stageRunIndex: context.stageRunIndex,
+        workspacePath: args.workspacePath,
+        ownerStageId: context.ownerStageId,
+        sessionMode: context.sessionMode,
+        stageSessionPath: args.stageSessionPath,
+        persistedSession: context.persistedSession,
+    };
+}
+async function maybeExerciseReadiness(args, plan, issues) {
+    const checkReadiness = args.provider.checkReadiness;
+    if (typeof checkReadiness !== "function") {
+        return;
+    }
+    const readiness = await captureAsyncIssue(issues, "provider.checkReadiness", () => checkReadiness({ repoRoot: args.repoRoot, runtimeHome: args.runtimeHome, plan }));
+    if (!readiness) {
+        return;
+    }
+    if (!Array.isArray(readiness.availability_errors)) {
+        issues.push("provider.checkReadiness(args) must return { availability_errors: string[] }.");
+        return;
+    }
+    if (readiness.availability_errors.length > 0) {
+        issues.push(`provider.checkReadiness returned availability errors: ${readiness.availability_errors.join("; ")}`);
+    }
+}
+function createAdapter(provider, issues) {
+    try {
+        const adapter = provider.create();
+        if (!adapter || typeof adapter !== "object") {
+            issues.push("provider.create must return a harness adapter object.");
+            return null;
+        }
+        return adapter;
+    }
+    catch (error) {
+        issues.push(`provider.create threw: ${formatError(error)}`);
+        return null;
+    }
+}
+function validateAdapterBasics(provider, adapter, plan, issues) {
+    if (adapter.manifest.id !== provider.manifest.id) {
+        issues.push(`adapter.manifest.id (${JSON.stringify(adapter.manifest.id)}) must match provider.manifest.id (${JSON.stringify(provider.manifest.id)}).`);
+    }
+    let ignoredEntries;
+    try {
+        ignoredEntries = adapter.getManagedWorkspaceIgnoreEntries(plan);
+    }
+    catch (error) {
+        issues.push(`adapter.getManagedWorkspaceIgnoreEntries threw: ${formatError(error)}`);
+        return;
+    }
+    if (!Array.isArray(ignoredEntries)) {
+        issues.push("adapter.getManagedWorkspaceIgnoreEntries(plan) must return an array.");
+    }
+    else if (ignoredEntries.some((value) => typeof value !== "string")) {
+        issues.push("adapter.getManagedWorkspaceIgnoreEntries(plan) must return only strings.");
+    }
+}
+function createDefaultBehaviorPlan(provider) {
+    const { defaults, id, supported_workspace_modes: workspaceModes } = provider.manifest;
+    const harness = {
+        id,
+        auth: normalizeHarnessAuth(defaults.auth),
+        turn_timeout_ms: defaults.turn_timeout_ms ?? 3_600_000,
+        stall_timeout_ms: defaults.stall_timeout_ms ?? 300_000,
+        config: normalizeJsonRecord(defaults.config),
+        retry: { max_retries: 0, base_delay_ms: 1_000, max_backoff_ms: 5_000 },
+        cancel: { graceful_timeout_ms: 2_000, hard_kill_timeout_ms: 1_000 },
+    };
+    if (defaults.model) {
+        harness.model = defaults.model;
+    }
+    if (defaults.effort) {
+        harness.effort = defaults.effort;
+    }
+    return {
+        workspace: { mode: workspaceModes[0] ?? "managed", prune_ttl_seconds: 604_800 },
+        harness,
+    };
+}
+async function seedDefaultSecretRefEnv(plan, repoRoot) {
+    const auth = plan.harness.auth;
+    if (!isJsonRecord(auth) || auth.strategy !== "secret_ref") {
+        return;
+    }
+    const ref = typeof auth.ref === "string" ? auth.ref.trim() : "";
+    if (!ref) {
+        return;
+    }
+    const value = `FLOW_TEST_${ref.toUpperCase().replace(/[^A-Z0-9_]+/gu, "_")}`;
+    await fs.writeFile(path.join(repoRoot, ".env"), `${ref}=${value}\n`, "utf8");
+}
+function validateStartedSession(session, expectedHarnessId, context, issues) {
+    if (!session || typeof session !== "object") {
+        issues.push("adapter.startSession(args) must return an ActiveHarnessSession object.");
+        return;
+    }
+    if (session.ownerStageId !== context.ownerStageId) {
+        issues.push(`startSession returned ownerStageId ${JSON.stringify(session.ownerStageId)} instead of ${JSON.stringify(context.ownerStageId)}.`);
+    }
+    if (!session.session || typeof session.session !== "object") {
+        issues.push("startSession must return session.session metadata.");
+        return;
+    }
+    for (const [field, actual, expected] of [
+        ["harness_id", session.session.harness_id, expectedHarnessId],
+        ["attempt_number", session.session.attempt_number, context.attemptNumber],
+        ["stage_id", session.session.stage_id, context.stageId],
+        ["stage_run_index", session.session.stage_run_index, context.stageRunIndex],
+    ]) {
+        if (actual !== expected) {
+            issues.push(`startSession returned ${field} ${JSON.stringify(actual)} instead of ${JSON.stringify(expected)}.`);
+        }
+    }
+    if (!session.session.harness_session || typeof session.session.harness_session !== "object") {
+        issues.push("startSession must return session.harness_session as an object.");
+    }
+}
+async function pushHookIssues(issues, result) {
+    const additionalIssues = await result;
+    if (Array.isArray(additionalIssues)) {
+        issues.push(...additionalIssues);
+    }
+}
+async function captureAsyncIssue(issues, label, action) {
+    try {
+        return await action();
+    }
+    catch (error) {
+        issues.push(`${label}: ${formatError(error)}`);
+        return null;
+    }
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function normalizeHarnessAuth(value) {
+    return isJsonRecord(value) ? value : {};
+}
+function normalizeJsonRecord(value) {
+    return isJsonRecord(value) ? { ...value } : {};
+}
+function isJsonRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+async function ensureDir(targetPath) {
+    await fs.mkdir(targetPath, { recursive: true });
+}

package/dist/conformance.d.ts

@@ -0,0 +1,3 @@
+import type { HarnessProvider } from "./index.js";
+export declare function collectHarnessProviderConformanceIssues(provider: HarnessProvider<unknown>): string[];
+//# sourceMappingURL=conformance.d.ts.map

package/dist/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,eAAe,CAAC,OAAO,CAAC,GACjC,MAAM,EAAE,CAoBV"}

package/dist/conformance.js

@@ -0,0 +1,37 @@
+export function collectHarnessProviderConformanceIssues(provider) {
+    const issues = [];
+    const manifest = provider.manifest;
+    validateManifest(manifest, issues);
+    if (!provider.schemas) {
+        issues.push("provider.schemas is required.");
+    }
+    else {
+        if (!provider.schemas.auth) {
+            issues.push("provider.schemas.auth is required.");
+        }
+        if (!provider.schemas.config) {
+            issues.push("provider.schemas.config is required.");
+        }
+    }
+    if (typeof provider.create !== "function") {
+        issues.push("provider.create must be a function.");
+    }
+    return issues;
+}
+function validateManifest(manifest, issues) {
+    if (!manifest.id?.trim()) {
+        issues.push("manifest.id must be a non-empty string.");
+    }
+    if (!manifest.display_name?.trim()) {
+        issues.push("manifest.display_name must be a non-empty string.");
+    }
+    if (!manifest.auth_schema) {
+        issues.push("manifest.auth_schema is required.");
+    }
+    if (!manifest.config_schema) {
+        issues.push("manifest.config_schema is required.");
+    }
+    if (!Array.isArray(manifest.supported_workspace_modes) || manifest.supported_workspace_modes.length === 0) {
+        issues.push("manifest.supported_workspace_modes must declare at least one mode.");
+    }
+}

package/dist/global-skills.d.ts

@@ -0,0 +1,22 @@
+import type { GlobalSkillCatalog, GlobalSkillCatalogEntry, GlobalSkillProviderSupport } from "./types.js";
+export declare function globalSkillsRoot(homeDir: string): string;
+export declare function globalDisabledSkillsRoot(homeDir: string): string;
+export declare function listGlobalSkills(args: {
+    homeDir: string;
+    providerSupport?: readonly GlobalSkillProviderSupport[];
+}): Promise<GlobalSkillCatalog>;
+export declare function updateGlobalSkill(args: {
+    enabled: boolean;
+    homeDir: string;
+    providerSupport?: readonly GlobalSkillProviderSupport[];
+    skillId: string;
+}): Promise<GlobalSkillCatalogEntry>;
+export declare function projectGlobalSkills(args: {
+    sourceHomeDir: string;
+    targetHomeDir: string;
+}): Promise<void>;
+export declare function syncEnabledGlobalSkillsToTarget(args: {
+    sourceHomeDir: string;
+    targetRoot: string;
+}): Promise<void>;
+//# sourceMappingURL=global-skills.d.ts.map

package/dist/global-skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-skills.d.ts","sourceRoot":"","sources":["../src/global-skills.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,kBAAkB,EAClB,uBAAuB,EACvB,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAOpB,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;CACzD,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAK9B;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;IACxD,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAuBnC;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhB;AAED,wBAAsB,+BAA+B,CAAC,IAAI,EAAE;IAC1D,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhB"}

package/dist/global-skills.js

@@ -0,0 +1,168 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+export function globalSkillsRoot(homeDir) {
+    return path.join(homeDir, ".agents", "skills");
+}
+export function globalDisabledSkillsRoot(homeDir) {
+    return path.join(homeDir, ".agents", ".disabled-skills");
+}
+export async function listGlobalSkills(args) {
+    const skills = await discoverGlobalSkillRecords(args.homeDir);
+    return {
+        skills: skills.map((skill) => toCatalogEntry(skill, args.providerSupport)),
+    };
+}
+export async function updateGlobalSkill(args) {
+    const skills = await discoverGlobalSkillRecords(args.homeDir);
+    const skill = skills.find((entry) => entry.id === args.skillId);
+    if (!skill) {
+        throw new Error(`Unknown global skill id: ${args.skillId}`);
+    }
+    if (skill.enabled !== args.enabled) {
+        const targetRoot = args.enabled
+            ? globalSkillsRoot(args.homeDir)
+            : globalDisabledSkillsRoot(args.homeDir);
+        const targetPath = path.join(targetRoot, skill.name);
+        await fs.mkdir(targetRoot, { recursive: true });
+        await fs.rm(targetPath, { recursive: true, force: true });
+        await fs.rename(skill.sourcePath, targetPath);
+    }
+    const updated = (await discoverGlobalSkillRecords(args.homeDir)).find((entry) => entry.id === args.skillId);
+    if (!updated) {
+        throw new Error(`Global skill disappeared after update: ${args.skillId}`);
+    }
+    return toCatalogEntry(updated, args.providerSupport);
+}
+export async function projectGlobalSkills(args) {
+    const targetRoot = globalSkillsRoot(args.targetHomeDir);
+    await syncEnabledGlobalSkillsToTarget({
+        sourceHomeDir: args.sourceHomeDir,
+        targetRoot,
+    });
+    await fs.rm(globalDisabledSkillsRoot(args.targetHomeDir), {
+        recursive: true,
+        force: true,
+    });
+}
+export async function syncEnabledGlobalSkillsToTarget(args) {
+    const skills = await discoverGlobalSkillRecords(args.sourceHomeDir);
+    await fs.rm(args.targetRoot, { recursive: true, force: true });
+    for (const skill of skills) {
+        if (!skill.enabled) {
+            continue;
+        }
+        const targetPath = path.join(args.targetRoot, skill.name);
+        await fs.mkdir(args.targetRoot, { recursive: true });
+        await fs.cp(skill.sourcePath, targetPath, {
+            recursive: true,
+            dereference: true,
+            errorOnExist: false,
+            force: true,
+        });
+    }
+}
+async function discoverGlobalSkillRecords(homeDir) {
+    const records = new Map();
+    for (const enabled of [true, false]) {
+        const root = enabled ? globalSkillsRoot(homeDir) : globalDisabledSkillsRoot(homeDir);
+        for (const entry of await discoverSkillDirectories(root)) {
+            if (records.has(entry.name)) {
+                continue;
+            }
+            const markdown = await fs.readFile(path.join(entry.path, "SKILL.md"), "utf8");
+            records.set(entry.name, {
+                id: entry.name,
+                label: readSkillLabel(markdown, entry.name),
+                summary: readSkillSummary(markdown),
+                enabled,
+                name: entry.name,
+                sourcePath: entry.path,
+            });
+        }
+    }
+    return [...records.values()].sort((left, right) => left.label.localeCompare(right.label));
+}
+async function discoverSkillDirectories(root) {
+    let entries;
+    try {
+        entries = await fs.readdir(root, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+    const skills = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith(".")) {
+            continue;
+        }
+        if (!entry.isDirectory() && !entry.isSymbolicLink()) {
+            continue;
+        }
+        const skillDir = path.join(root, entry.name);
+        try {
+            const stat = await fs.stat(path.join(skillDir, "SKILL.md"));
+            if (!stat.isFile()) {
+                continue;
+            }
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                continue;
+            }
+            throw error;
+        }
+        skills.push({
+            name: entry.name,
+            path: skillDir,
+        });
+    }
+    return skills.sort((left, right) => left.name.localeCompare(right.name));
+}
+function toCatalogEntry(skill, providerSupport) {
+    return {
+        id: skill.id,
+        label: skill.label,
+        summary: skill.summary,
+        enabled: skill.enabled,
+        providerSupport: [...(providerSupport ?? [])],
+    };
+}
+function readSkillLabel(markdown, fallback) {
+    for (const line of contentLines(markdown)) {
+        const match = line.match(/^#\s+(.+)$/u);
+        if (match?.[1]?.trim()) {
+            return match[1].trim();
+        }
+    }
+    return fallback;
+}
+function readSkillSummary(markdown) {
+    const paragraph = [];
+    let inCodeBlock = false;
+    for (const line of contentLines(markdown)) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("```")) {
+            inCodeBlock = !inCodeBlock;
+            continue;
+        }
+        if (inCodeBlock || trimmed.length === 0 || trimmed.startsWith("#")) {
+            if (paragraph.length > 0 && trimmed.length === 0) {
+                break;
+            }
+            continue;
+        }
+        paragraph.push(trimmed);
+    }
+    return paragraph.length > 0 ? paragraph.join(" ") : null;
+}
+function contentLines(markdown) {
+    const lines = markdown.split(/\r?\n/u);
+    if (lines[0]?.trim() !== "---") {
+        return lines;
+    }
+    const closingIndex = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+    return closingIndex >= 0 ? lines.slice(closingIndex + 1) : lines;
+}

package/dist/index.d.ts

@@ -0,0 +1,138 @@
+import { z } from "zod";
+import type { ExecutionTrace, HarnessEvent, HarnessAuth, HarnessSession, JsonValue, WorkflowDocument, WorkflowHarness, WorkspaceMode } from "./types.js";
+export * from "./behavior-contract.js";
+export * from "./access-contracts.js";
+export * from "./conformance.js";
+export * from "./global-skills.js";
+export * from "./internal-utils.js";
+export * from "./json-rpc.js";
+export * from "./managed-runtime.js";
+export * from "./model-config.js";
+export * from "./normalized-activity.js";
+export * from "./prepare.js";
+export * from "./process-env.js";
+export * from "./session-runtime.js";
+export * from "./trace-builder.js";
+export * from "./trace-replay.js";
+export * from "./tool-semantics.js";
+export * from "./types.js";
+export interface HarnessExecutionPlan extends Pick<WorkflowDocument, "workspace"> {
+    harness: WorkflowHarness;
+}
+type WorkflowHarnessCancel = HarnessExecutionPlan["harness"]["cancel"];
+export interface HarnessCapabilities {
+    supports_resume: boolean;
+    supports_interrupt: boolean;
+    required_runtime_capabilities: string[];
+}
+export interface HarnessManifest {
+    id: string;
+    display_name: string;
+    auth_schema: JsonValue;
+    config_schema: JsonValue;
+    defaults: {
+        auth?: HarnessAuth;
+        model?: string;
+        effort?: string;
+        turn_timeout_ms?: number;
+        stall_timeout_ms?: number;
+        config?: Record<string, JsonValue>;
+    };
+    capabilities: HarnessCapabilities;
+    supported_workspace_modes: WorkspaceMode[];
+}
+export interface HarnessValidationSchemas<TAuth extends Record<string, JsonValue> = Record<string, JsonValue>, TConfig extends Record<string, JsonValue> = Record<string, JsonValue>> {
+    auth: z.ZodType<TAuth>;
+    config: z.ZodType<TConfig>;
+}
+export interface HarnessReadinessContext {
+    repoRoot: string;
+    runtimeHome: string;
+    parentEnv?: NodeJS.ProcessEnv;
+}
+export interface HarnessReadinessCheckArgs extends HarnessReadinessContext {
+    plan: HarnessExecutionPlan;
+}
+export interface HarnessReadinessResult {
+    availability_errors: string[];
+}
+export interface HarnessTurnLiveBatch {
+    harnessEvents: HarnessEvent[];
+    traceBundle: {
+        spans: ExecutionTrace["spans"];
+        events: ExecutionTrace["events"];
+        summaries: ExecutionTrace["summaries"];
+    };
+}
+export interface HarnessTurnLivePersistence {
+    flushWindowMs?: number;
+    onFlush: (batch: HarnessTurnLiveBatch) => Promise<void>;
+}
+export interface HarnessRunResult {
+    sessionId: string;
+    finalOutput: string;
+    trace: ExecutionTrace;
+    events: HarnessEvent[];
+}
+export type HarnessSessionMode = "fresh" | "resume";
+export interface StartSessionArgs {
+    repoRoot: string;
+    runtimeHome: string;
+    plan: HarnessExecutionPlan;
+    ownerId: string;
+    executionId: string;
+    attemptNumber: number;
+    stageId: string;
+    stageRunIndex: number;
+    workspacePath: string;
+    ownerStageId: string;
+    sessionMode: HarnessSessionMode;
+    persistedSession: Record<string, JsonValue> | null;
+    stageSessionPath: string;
+}
+export interface StartTurnArgs {
+    prompt: string;
+    eventsFile: string;
+    rawEventsFile: string;
+    stageSpanId: string;
+    plan: HarnessExecutionPlan;
+    livePersistence?: HarnessTurnLivePersistence;
+}
+export interface ActiveHarnessSession<TState = unknown> {
+    adapter: HarnessAdapter<TState>;
+    ownerStageId: string;
+    session: HarnessSession;
+    state: TState;
+}
+export interface HarnessAdapter<TState = unknown> {
+    readonly manifest: HarnessManifest;
+    getManagedWorkspaceIgnoreEntries(plan: HarnessExecutionPlan): string[];
+    startSession(args: StartSessionArgs): Promise<ActiveHarnessSession<TState>>;
+    startTurn(context: ActiveHarnessSession<TState>, args: StartTurnArgs): Promise<HarnessRunResult>;
+    interruptTurn(context: ActiveHarnessSession<TState>): Promise<void>;
+    closeSession(context: ActiveHarnessSession<TState>, cancelConfig?: WorkflowHarnessCancel): Promise<void>;
+}
+export interface HarnessProvider<TState = unknown, TAuth extends Record<string, JsonValue> = Record<string, JsonValue>, TConfig extends Record<string, JsonValue> = Record<string, JsonValue>> {
+    readonly manifest: HarnessManifest;
+    readonly schemas: HarnessValidationSchemas<TAuth, TConfig>;
+    checkReadiness?(args: HarnessReadinessCheckArgs): Promise<HarnessReadinessResult>;
+    create(): HarnessAdapter<TState>;
+}
+export declare function defineHarnessProvider<TState = unknown, TAuth extends Record<string, JsonValue> = Record<string, JsonValue>, TConfig extends Record<string, JsonValue> = Record<string, JsonValue>>(factory: HarnessProvider<TState, TAuth, TConfig>): HarnessProvider<TState, TAuth, TConfig>;
+export declare function createCliHarnessManifest(args: {
+    id: string;
+    displayName?: string;
+    auth: z.ZodTypeAny;
+    config: z.ZodTypeAny;
+    defaults?: {
+        auth?: HarnessAuth;
+        model?: string;
+        effort?: string;
+        turn_timeout_ms?: number;
+        stall_timeout_ms?: number;
+        config?: Record<string, JsonValue>;
+    };
+    capabilities: HarnessManifest["capabilities"];
+    supportedWorkspaceModes: readonly WorkspaceMode[];
+}): HarnessManifest;
+//# sourceMappingURL=index.d.ts.map