usesteady 0.1.0-alpha.1

package/dist/src/skills/audit.d.ts

@@ -0,0 +1,118 @@
+/**
+ * UseSteady Skills v1 — audit logging stub (file 7 of 8).
+ *
+ * Single responsibility: turn SkillInvocationResult objects into SkillAuditRecord
+ * objects and provide an interface for writing those records to a persistence layer.
+ *
+ * What this file owns:
+ *   - Pure record builders (buildAuditRecord, buildAuditRecords) — synchronous,
+ *     no I/O, fully deterministic
+ *   - The AuditSink interface — the hook for later persistence wiring
+ *   - Two built-in sinks: NULL_AUDIT_SINK (testing) and CONSOLE_AUDIT_SINK (dev)
+ *
+ * What this file does NOT own:
+ *   - Deciding which invocations to audit (always all of them)
+ *   - Filtering, sampling, or dropping records
+ *   - Writing to disk, database, or network directly (that lives in concrete AuditSink implementations)
+ *   - Any authority over execution, approval, or policy
+ *
+ * Persistence compatibility:
+ *   SkillAuditRecord is fully JSON-serialisable (no functions, no circular refs,
+ *   no non-primitive types beyond Date). Consumers calling JSON.stringify on a
+ *   record will get a complete, human-readable snapshot suitable for any store.
+ */
+import type { InvokeSkillsResult, SkillInvocationResult } from './invocation.js';
+import { type SkillAuditRecord, type TriggerReason } from './types.js';
+/**
+ * Options for the audit record builders.
+ * All fields are optional — sensible defaults are applied when absent.
+ */
+export interface BuildAuditOptions {
+    /**
+     * The timestamp to stamp on every record built in this call.
+     * Callers should pass a fixed value when building multiple records for the
+     * same invocation batch so all records share the same `invokedAt`.
+     * Defaults to `new Date()` when absent.
+     */
+    readonly invokedAt?: Date;
+    /**
+     * Map from skill name to its absolute SKILL.md source path.
+     * When provided, `sourcePath` is populated on each record.
+     * When absent, `sourcePath` is omitted entirely from all records.
+     * Build this map from the Skill objects in the registry if you have them.
+     */
+    readonly sourcePaths?: ReadonlyMap<string, string>;
+}
+/**
+ * Build one SkillAuditRecord from a SkillInvocationResult and its execution context.
+ *
+ * The `triggerReason` and `rawInput` come from InvokeSkillsResult; they are
+ * passed separately here so this function is also usable outside the batch path.
+ *
+ * exactOptionalPropertyTypes compliance:
+ *   `sourcePath` and `rejectionReason` are physically absent (not set to
+ *   undefined) when they have no value — conditional spread achieves this.
+ */
+export declare function buildAuditRecord(result: SkillInvocationResult, triggerReason: TriggerReason, rawInput: string, options?: BuildAuditOptions): SkillAuditRecord;
+/**
+ * Build one SkillAuditRecord for each result in an InvokeSkillsResult.
+ *
+ * All records in the batch share the same `invokedAt` timestamp so they can
+ * be correlated as a single invocation event. A fixed timestamp is captured
+ * once before the map to avoid per-record clock skew.
+ *
+ * Returns records in the same order as `invokeResult.results` (priority order).
+ */
+export declare function buildAuditRecords(invokeResult: InvokeSkillsResult, options?: BuildAuditOptions): readonly SkillAuditRecord[];
+/**
+ * The persistence hook. Implementations write SkillAuditRecord objects to
+ * whatever store is appropriate (file, DB, structured log, HTTP endpoint).
+ *
+ * Contract:
+ *   - Must not mutate the record.
+ *   - Must not throw synchronously — wrap errors in the returned Promise.
+ *   - Must not block the calling skill invocation path (fire-and-forget is acceptable).
+ *   - In v1, third-party sink implementations are not loaded automatically.
+ */
+export interface AuditSink {
+    record(audit: SkillAuditRecord): Promise<void>;
+}
+/**
+ * A no-op AuditSink. Use in tests or when audit persistence is not configured.
+ * Records are silently discarded. No I/O, no side effects.
+ */
+export declare const NULL_AUDIT_SINK: AuditSink;
+/**
+ * A development AuditSink that writes a compact JSON line to stdout.
+ * Not for production use — use a structured logging sink there.
+ *
+ * Output format (one JSON object per line):
+ * {
+ *   "skill":    "<name>@<version>",
+ *   "outcome":  "accepted" | "rejected",
+ *   "schema":   "<output_schema>",
+ *   "trigger":  "<kind>",
+ *   "input":    "<first 80 chars of rawInput>",
+ *   "at":       "<ISO 8601 timestamp>",
+ *   "reason":   "<rejectionReason>" — only present when rejected
+ * }
+ */
+export declare const CONSOLE_AUDIT_SINK: AuditSink;
+/**
+ * Build a ReadonlyMap<string, string> from skill name to source path.
+ * Pass the result as `options.sourcePaths` to populate `sourcePath` in
+ * audit records.
+ *
+ * Usage:
+ *   const sourcePaths = buildSourcePathMap(registry.all);
+ *   const records = buildAuditRecords(result, { sourcePaths });
+ *
+ * Accepts any iterable of objects with `metadata.name` and `sourcePath`.
+ */
+export declare function buildSourcePathMap(skills: Iterable<{
+    readonly metadata: {
+        readonly name: string;
+    };
+    readonly sourcePath: string;
+}>): ReadonlyMap<string, string>;
+//# sourceMappingURL=audit.d.ts.map

package/dist/src/skills/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../src/skills/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACjF,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAMpB;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpD;AAMD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,qBAAqB,EAC7B,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,gBAAgB,CAsBlB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,kBAAkB,EAChC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,SAAS,gBAAgB,EAAE,CAmB7B;AAMD;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAMD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,SAK7B,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAgBhC,CAAC;AAMF;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,QAAQ,CAAC;IAAE,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GAC9F,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAM7B"}

package/dist/src/skills/audit.js

@@ -0,0 +1,147 @@
+/**
+ * UseSteady Skills v1 — audit logging stub (file 7 of 8).
+ *
+ * Single responsibility: turn SkillInvocationResult objects into SkillAuditRecord
+ * objects and provide an interface for writing those records to a persistence layer.
+ *
+ * What this file owns:
+ *   - Pure record builders (buildAuditRecord, buildAuditRecords) — synchronous,
+ *     no I/O, fully deterministic
+ *   - The AuditSink interface — the hook for later persistence wiring
+ *   - Two built-in sinks: NULL_AUDIT_SINK (testing) and CONSOLE_AUDIT_SINK (dev)
+ *
+ * What this file does NOT own:
+ *   - Deciding which invocations to audit (always all of them)
+ *   - Filtering, sampling, or dropping records
+ *   - Writing to disk, database, or network directly (that lives in concrete AuditSink implementations)
+ *   - Any authority over execution, approval, or policy
+ *
+ * Persistence compatibility:
+ *   SkillAuditRecord is fully JSON-serialisable (no functions, no circular refs,
+ *   no non-primitive types beyond Date). Consumers calling JSON.stringify on a
+ *   record will get a complete, human-readable snapshot suitable for any store.
+ */
+// ---------------------------------------------------------------------------
+// Single-record builder
+// ---------------------------------------------------------------------------
+/**
+ * Build one SkillAuditRecord from a SkillInvocationResult and its execution context.
+ *
+ * The `triggerReason` and `rawInput` come from InvokeSkillsResult; they are
+ * passed separately here so this function is also usable outside the batch path.
+ *
+ * exactOptionalPropertyTypes compliance:
+ *   `sourcePath` and `rejectionReason` are physically absent (not set to
+ *   undefined) when they have no value — conditional spread achieves this.
+ */
+export function buildAuditRecord(result, triggerReason, rawInput, options) {
+    const invokedAt = options?.invokedAt ?? new Date();
+    const sourcePath = options?.sourcePaths?.get(result.skillName);
+    // `result.rejectionReason` is `string | undefined` because the field is `?: string`.
+    // We check for its presence explicitly rather than comparing to undefined so the
+    // conditional spread respects exactOptionalPropertyTypes on the target type.
+    const hasRejectionReason = 'rejectionReason' in result;
+    return {
+        skillName: result.skillName,
+        skillVersion: result.skillVersion,
+        outputSchema: result.outputSchema,
+        rawOutput: result.rawOutput,
+        validationOutcome: result.validationOutcome,
+        invokedAt,
+        triggerReason,
+        rawInput,
+        // Optional fields — physically absent when not applicable.
+        ...(sourcePath !== undefined ? { sourcePath } : {}),
+        ...(hasRejectionReason ? { rejectionReason: result.rejectionReason } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// Batch builder
+// ---------------------------------------------------------------------------
+/**
+ * Build one SkillAuditRecord for each result in an InvokeSkillsResult.
+ *
+ * All records in the batch share the same `invokedAt` timestamp so they can
+ * be correlated as a single invocation event. A fixed timestamp is captured
+ * once before the map to avoid per-record clock skew.
+ *
+ * Returns records in the same order as `invokeResult.results` (priority order).
+ */
+export function buildAuditRecords(invokeResult, options) {
+    // Capture a single timestamp for the whole batch.
+    const invokedAt = options?.invokedAt ?? new Date();
+    const sourcePaths = options?.sourcePaths;
+    // Rebuild a concrete options object so buildAuditRecord uses the fixed timestamp.
+    const batchOptions = {
+        invokedAt,
+        ...(sourcePaths !== undefined ? { sourcePaths } : {}),
+    };
+    return invokeResult.results.map((result) => buildAuditRecord(result, invokeResult.triggerReason, invokeResult.rawInput, batchOptions));
+}
+// ---------------------------------------------------------------------------
+// Built-in sinks
+// ---------------------------------------------------------------------------
+/**
+ * A no-op AuditSink. Use in tests or when audit persistence is not configured.
+ * Records are silently discarded. No I/O, no side effects.
+ */
+export const NULL_AUDIT_SINK = {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    async record(_audit) {
+        // Intentional no-op.
+    },
+};
+/**
+ * A development AuditSink that writes a compact JSON line to stdout.
+ * Not for production use — use a structured logging sink there.
+ *
+ * Output format (one JSON object per line):
+ * {
+ *   "skill":    "<name>@<version>",
+ *   "outcome":  "accepted" | "rejected",
+ *   "schema":   "<output_schema>",
+ *   "trigger":  "<kind>",
+ *   "input":    "<first 80 chars of rawInput>",
+ *   "at":       "<ISO 8601 timestamp>",
+ *   "reason":   "<rejectionReason>" — only present when rejected
+ * }
+ */
+export const CONSOLE_AUDIT_SINK = {
+    async record(audit) {
+        // Build a plain object; JSON.stringify omits undefined values automatically,
+        // so `reason` is only present in the output when rejectionReason is defined.
+        const entry = {
+            skill: `${audit.skillName}@${audit.skillVersion}`,
+            outcome: audit.validationOutcome,
+            schema: audit.outputSchema,
+            trigger: audit.triggerReason.kind,
+            input: audit.rawInput.slice(0, 80),
+            at: audit.invokedAt.toISOString(),
+            reason: audit.rejectionReason, // undefined → omitted by JSON.stringify
+            source: audit.sourcePath, // undefined → omitted by JSON.stringify
+        };
+        console.log('[SkillAudit]', JSON.stringify(entry));
+    },
+};
+// ---------------------------------------------------------------------------
+// Utility — build a source path map from a registry
+// ---------------------------------------------------------------------------
+/**
+ * Build a ReadonlyMap<string, string> from skill name to source path.
+ * Pass the result as `options.sourcePaths` to populate `sourcePath` in
+ * audit records.
+ *
+ * Usage:
+ *   const sourcePaths = buildSourcePathMap(registry.all);
+ *   const records = buildAuditRecords(result, { sourcePaths });
+ *
+ * Accepts any iterable of objects with `metadata.name` and `sourcePath`.
+ */
+export function buildSourcePathMap(skills) {
+    const map = new Map();
+    for (const skill of skills) {
+        map.set(skill.metadata.name, skill.sourcePath);
+    }
+    return map;
+}
+//# sourceMappingURL=audit.js.map

package/dist/src/skills/audit.js.map

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

package/dist/src/skills/invocation.d.ts

@@ -0,0 +1,131 @@
+/**
+ * UseSteady Skills v1 — invocation helper (file 6 of 8).
+ *
+ * This file is the boundary between the registry and anything that actually
+ * produces skill output. It is the most sensitive module in the system.
+ *
+ * What this file owns:
+ *   - The SkillModelAdapter interface (the only abstraction over output production)
+ *   - Per-skill invocation with full error isolation
+ *   - Output schema validation (adapter output must match the skill's declared schema)
+ *   - Per-invocation provenance (name, version, schema, raw output, outcome)
+ *   - The aggregate InvokeSkillsResult shape the caller receives
+ *
+ * What this file explicitly does NOT own:
+ *   - Deciding whether the deterministic parser was right (caller's responsibility)
+ *   - Deciding whether input is "plausibly actionable" (caller's responsibility)
+ *   - Deciding policy or approval (never, anywhere in the Skills layer)
+ *   - Merging skill output into canonical execution state (UseSteady core's job)
+ *   - Auto-fallback across kinds (there is no fallback here)
+ *   - Choosing a different trigger kind than what the caller provided
+ *
+ * Deterministic-first boundary:
+ *   Callers decide to invoke skills — this file does not. A caller invokes
+ *   this helper only after the deterministic parser has run and its result
+ *   made a trigger decision. The TriggerReason parameter carries that decision
+ *   forward so it is preserved in every provenance record.
+ */
+import { type LoadedSkillRegistry, type Skill, type SkillOutput, type SkillOutputSchema, type TriggerReason } from './types.js';
+/**
+ * The only abstraction point over output production in the Skills v1 layer.
+ *
+ * An adapter receives a fully loaded Skill (metadata + body instructions) and
+ * the raw user input, then produces the skill's typed output or null.
+ *
+ * Contract:
+ *   - Return a SkillOutput whose `schema` field matches skill.metadata.output_schema.
+ *   - Return null to signal "this skill has nothing to contribute for this input"
+ *     without constituting a failure (distinct from an empty candidates/steps/suggestions
+ *     array, which signals "the skill ran and found nothing applicable").
+ *   - May throw — the invocation helper wraps all adapter errors as rejections.
+ *   - Must NOT execute filesystem operations, approve anything, or call UseSteady core.
+ *
+ * In production this wraps an LLM call. In tests it is a controlled stub.
+ */
+export interface SkillModelAdapter {
+    invoke(skill: Skill, rawInput: string): Promise<SkillOutput | null>;
+}
+/**
+ * The result of invoking one Skill via an adapter.
+ *
+ * Every field except `rejectionReason` is always present.
+ * `rejectionReason` is physically absent (not undefined) when the invocation
+ * was accepted — required by exactOptionalPropertyTypes: true.
+ *
+ * This shape carries enough information for the audit logger (file 7) to
+ * produce a SkillAuditRecord without re-querying the registry.
+ */
+export interface SkillInvocationResult {
+    readonly skillName: string;
+    readonly skillVersion: string;
+    readonly outputSchema: SkillOutputSchema;
+    /**
+     * The raw output returned by the adapter, or null if:
+     *   - the adapter returned null (declined to contribute), or
+     *   - the adapter threw an error.
+     * Even when rejected due to schema mismatch, the raw output is preserved
+     * here so the audit log captures what the adapter actually returned.
+     */
+    readonly rawOutput: SkillOutput | null;
+    readonly validationOutcome: 'accepted' | 'rejected';
+    /** Absent when accepted; present (as a string, not undefined) when rejected. */
+    readonly rejectionReason?: string;
+}
+/**
+ * The result of invoking all triggerable skills for a given trigger context.
+ *
+ * `results` is the full list including rejections — callers and the audit
+ * logger should use this for complete provenance.
+ *
+ * `accepted` is a convenience slice: only the non-null outputs from skills
+ * whose validationOutcome === 'accepted'. Callers presenting output to the
+ * user should iterate this list, not `results`.
+ */
+export interface InvokeSkillsResult {
+    readonly triggerReason: TriggerReason;
+    readonly rawInput: string;
+    /** All invocation results in priority order. May include rejections. */
+    readonly results: readonly SkillInvocationResult[];
+    /** Accepted, non-null outputs in priority order. May be empty. */
+    readonly accepted: readonly SkillOutput[];
+}
+export interface InvokeSkillsOptions {
+    readonly registry: LoadedSkillRegistry;
+    readonly triggerReason: TriggerReason;
+    /**
+     * The raw user input string, passed unchanged to each adapter invocation.
+     * Also stored in InvokeSkillsResult for provenance.
+     */
+    readonly rawInput: string;
+    readonly adapter: SkillModelAdapter;
+}
+/**
+ * Invoke all triggerable skills for a given trigger context and return their
+ * results with full provenance.
+ *
+ * Deterministic-first enforcement:
+ *   This function does not decide when to consult skills. The caller has
+ *   already made that decision by constructing a TriggerReason. This function
+ *   executes the decision — no more, no less.
+ *
+ * No auto-fallback:
+ *   If no skills are loaded for the trigger kind, or if all invocations are
+ *   rejected, the returned `accepted` array is empty. The caller decides what
+ *   to do with an empty result — this function does not try another kind.
+ *
+ * Ordering:
+ *   Skills are already in priority order from the registry (buildRegistry).
+ *   Results preserve that order. Promise.all runs adapter calls concurrently
+ *   but preserves input order in the output array.
+ *
+ * Isolation:
+ *   Each skill is invoked independently. An adapter error for one skill
+ *   becomes a rejection for that skill; other skills continue to run.
+ *
+ * @param options.registry      The loaded skill registry.
+ * @param options.triggerReason The trigger context — drives which skill kind is consulted.
+ * @param options.rawInput      The raw user input, passed unchanged to each adapter.
+ * @param options.adapter       The model adapter that produces skill output.
+ */
+export declare function invokeSkillsForTrigger(options: InvokeSkillsOptions): Promise<InvokeSkillsResult>;
+//# sourceMappingURL=invocation.d.ts.map

package/dist/src/skills/invocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation.d.ts","sourceRoot":"","sources":["../../../src/skills/invocation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,KAAK,EACV,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAMpB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACrE;AAMD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAAC;IACzC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,iBAAiB,EAAE,UAAU,GAAG,UAAU,CAAC;IACpD,gFAAgF;IAChF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAMD;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACnD,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;CAC3C;AAMD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACrC;AA+GD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAwB7B"}

package/dist/src/skills/invocation.js

@@ -0,0 +1,165 @@
+/**
+ * UseSteady Skills v1 — invocation helper (file 6 of 8).
+ *
+ * This file is the boundary between the registry and anything that actually
+ * produces skill output. It is the most sensitive module in the system.
+ *
+ * What this file owns:
+ *   - The SkillModelAdapter interface (the only abstraction over output production)
+ *   - Per-skill invocation with full error isolation
+ *   - Output schema validation (adapter output must match the skill's declared schema)
+ *   - Per-invocation provenance (name, version, schema, raw output, outcome)
+ *   - The aggregate InvokeSkillsResult shape the caller receives
+ *
+ * What this file explicitly does NOT own:
+ *   - Deciding whether the deterministic parser was right (caller's responsibility)
+ *   - Deciding whether input is "plausibly actionable" (caller's responsibility)
+ *   - Deciding policy or approval (never, anywhere in the Skills layer)
+ *   - Merging skill output into canonical execution state (UseSteady core's job)
+ *   - Auto-fallback across kinds (there is no fallback here)
+ *   - Choosing a different trigger kind than what the caller provided
+ *
+ * Deterministic-first boundary:
+ *   Callers decide to invoke skills — this file does not. A caller invokes
+ *   this helper only after the deterministic parser has run and its result
+ *   made a trigger decision. The TriggerReason parameter carries that decision
+ *   forward so it is preserved in every provenance record.
+ */
+import { getTriggerableSkills } from './registry.js';
+// ---------------------------------------------------------------------------
+// Internal — output schema validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate that the adapter's output schema matches the skill's declared schema.
+ *
+ * This is the only structural check the invocation helper performs.
+ * Full candidate/step/suggestion validation is the responsibility of the
+ * consumer (UseSteady's validation layer), not this boundary helper.
+ *
+ * The check compares `output.schema` against `skill.metadata.output_schema`.
+ * `skill.metadata.output_schema` was verified against KIND_SCHEMA_MAP at
+ * load time, so this check transitively enforces the kind→schema mapping.
+ */
+function validateAdapterOutput(skill, output) {
+    if (output.schema !== skill.metadata.output_schema) {
+        return {
+            valid: false,
+            reason: `Adapter returned schema "${output.schema}" ` +
+                `but skill "${skill.metadata.name}" declared "${skill.metadata.output_schema}". ` +
+                `Output is rejected; raw output preserved in provenance record.`,
+        };
+    }
+    return { valid: true };
+}
+// ---------------------------------------------------------------------------
+// Internal — single-skill invocation
+// ---------------------------------------------------------------------------
+/**
+ * Invoke one Skill via the adapter and return a provenance record.
+ *
+ * Failure modes and their outcomes:
+ *   Adapter throws       → rejected, rawOutput: null, rejectionReason: error message
+ *   Adapter returns null → rejected, rawOutput: null, rejectionReason: "declined"
+ *   Schema mismatch      → rejected, rawOutput: <raw> (preserved for audit)
+ *   Schema matches       → accepted, rawOutput: <output>
+ *
+ * exactOptionalPropertyTypes compliance:
+ *   `rejectionReason` is included only in rejected branches.
+ *   Accepted results omit the field entirely (not set to undefined).
+ */
+async function invokeOneSkill(skill, rawInput, adapter) {
+    // Provenance fields that are always present, regardless of outcome.
+    const provenance = {
+        skillName: skill.metadata.name,
+        skillVersion: skill.metadata.version,
+        outputSchema: skill.metadata.output_schema,
+    };
+    // ── Adapter call — isolated, any throw becomes a rejection ────────────────
+    let output;
+    try {
+        output = await adapter.invoke(skill, rawInput);
+    }
+    catch (err) {
+        return {
+            ...provenance,
+            rawOutput: null,
+            validationOutcome: 'rejected',
+            rejectionReason: `Adapter threw: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // ── null return — skill declined to contribute ────────────────────────────
+    if (output === null) {
+        return {
+            ...provenance,
+            rawOutput: null,
+            validationOutcome: 'rejected',
+            rejectionReason: 'Adapter returned null — skill has nothing to contribute for this input.',
+        };
+    }
+    // ── Schema validation ─────────────────────────────────────────────────────
+    const check = validateAdapterOutput(skill, output);
+    if (!check.valid) {
+        return {
+            ...provenance,
+            // Preserve raw output even on rejection so audit logs capture what
+            // the adapter actually returned, not just that it failed.
+            rawOutput: output,
+            validationOutcome: 'rejected',
+            rejectionReason: check.reason,
+        };
+    }
+    // ── Accepted — rejectionReason is absent (not set to undefined) ───────────
+    return {
+        ...provenance,
+        rawOutput: output,
+        validationOutcome: 'accepted',
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Invoke all triggerable skills for a given trigger context and return their
+ * results with full provenance.
+ *
+ * Deterministic-first enforcement:
+ *   This function does not decide when to consult skills. The caller has
+ *   already made that decision by constructing a TriggerReason. This function
+ *   executes the decision — no more, no less.
+ *
+ * No auto-fallback:
+ *   If no skills are loaded for the trigger kind, or if all invocations are
+ *   rejected, the returned `accepted` array is empty. The caller decides what
+ *   to do with an empty result — this function does not try another kind.
+ *
+ * Ordering:
+ *   Skills are already in priority order from the registry (buildRegistry).
+ *   Results preserve that order. Promise.all runs adapter calls concurrently
+ *   but preserves input order in the output array.
+ *
+ * Isolation:
+ *   Each skill is invoked independently. An adapter error for one skill
+ *   becomes a rejection for that skill; other skills continue to run.
+ *
+ * @param options.registry      The loaded skill registry.
+ * @param options.triggerReason The trigger context — drives which skill kind is consulted.
+ * @param options.rawInput      The raw user input, passed unchanged to each adapter.
+ * @param options.adapter       The model adapter that produces skill output.
+ */
+export async function invokeSkillsForTrigger(options) {
+    const { registry, triggerReason, rawInput, adapter } = options;
+    // Retrieve the skills eligible for this trigger context.
+    // No cross-kind fallback — if this list is empty, accepted will be empty.
+    const skills = getTriggerableSkills(registry, triggerReason);
+    // Invoke each skill independently and concurrently.
+    // Skills are already in priority order; Promise.all preserves that order.
+    const results = await Promise.all(skills.map((skill) => invokeOneSkill(skill, rawInput, adapter)));
+    // Extract accepted outputs for caller convenience.
+    // The type predicate narrows rawOutput from SkillOutput | null to SkillOutput
+    // so the .map below can safely return SkillOutput (not SkillOutput | null).
+    const accepted = results
+        .filter((r) => r.validationOutcome === 'accepted' && r.rawOutput !== null)
+        .map((r) => r.rawOutput);
+    return { triggerReason, rawInput, results, accepted };
+}
+//# sourceMappingURL=invocation.js.map

package/dist/src/skills/invocation.js.map

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

package/dist/src/skills/loader.d.ts

@@ -0,0 +1,70 @@
+/**
+ * UseSteady Skills v1 — loader/scanner (file 4 of 8).
+ *
+ * Single responsibility: discover all SKILL.md files under a base directory,
+ * pipe each through the parser → validator chain, and return a sorted registry
+ * of accepted skills alongside a full list of structured rejections.
+ *
+ * Design rules:
+ *   - A broken skill produces a rejection entry and is skipped. It never
+ *     prevents other skills from loading (partial-failure guarantee).
+ *   - Accepted skills are sorted deterministically:
+ *       1. by kind (interpretation → workflow_generation → recovery)
+ *       2. then ascending priority (lower number = evaluated first)
+ *       3. then source path as a stable alphabetical tie-break
+ *   - Each rejection carries its file path, the pipeline stage that failed
+ *     (parser or validator), and the full structured issue list.
+ *   - No invocation logic, no audit writes, no side effects beyond I/O.
+ */
+import { type Skill, type SkillValidationIssue, type LoadedSkillRegistry } from './types.js';
+/**
+ * A skill file that was found but could not be loaded at either the
+ * parser or validator stage.
+ */
+export interface SkillRejection {
+    readonly sourcePath: string;
+    /** Whether the failure occurred during parsing or validation. */
+    readonly stage: 'parser' | 'validator';
+    /**
+     * All structured issues collected at that stage.
+     * Parser issues are syntax errors; validator issues are spec violations.
+     * Always non-empty.
+     */
+    readonly issues: readonly SkillValidationIssue[];
+}
+/** The complete result of a scan pass. */
+export interface ScanResult {
+    readonly registry: LoadedSkillRegistry;
+    readonly rejections: readonly SkillRejection[];
+}
+/**
+ * Build a LoadedSkillRegistry from a list of accepted Skill objects.
+ *
+ * Skills are sorted once via compareSkills, then distributed into per-kind
+ * buckets using an exhaustive switch (no index-signature access, safe under
+ * noUncheckedIndexedAccess).
+ *
+ * The `loadedAt` timestamp is recorded here so that callers can compare
+ * registry age against source change timestamps if needed.
+ */
+export declare function buildRegistry(accepted: readonly Skill[]): LoadedSkillRegistry;
+/**
+ * Scan `baseDir` recursively for SKILL.md files, parse and validate each one,
+ * and return a sorted registry of accepted skills alongside a full rejection list.
+ *
+ * Partial-failure guarantee
+ * ─────────────────────────
+ * Each file is processed independently inside a try/catch. A parse failure,
+ * validation failure, or unexpected error for one file produces a SkillRejection
+ * and is skipped. Other files continue to load normally.
+ *
+ * The one unrecoverable case is if the directory itself cannot be read (ENOENT,
+ * EACCES, etc.) — that throws SkillLoadError(SCAN_FAILED) because there is
+ * nothing meaningful to return.
+ *
+ * @param baseDir Absolute path to the skills root directory.
+ *
+ * @throws SkillLoadError(SCAN_FAILED) if baseDir cannot be read.
+ */
+export declare function scanSkillsDirectory(baseDir: string): Promise<ScanResult>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/src/skills/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/skills/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,EAGL,KAAK,KAAK,EAEV,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,YAAY,CAAC;AAMpB;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,WAAW,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAClD;AAED,0CAA0C;AAC1C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,SAAS,cAAc,EAAE,CAAC;CAChD;AA0ED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,SAAS,KAAK,EAAE,GAAG,mBAAmB,CA8B7E;AAsCD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAkD9E"}