@a5c-ai/agent-platform 5.0.1-staging.04ca6ab00d21

package/dist/session/types.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Session state management types for babysitter orchestration.
+ * These types represent the state stored in markdown files with YAML frontmatter.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionErrorCode = exports.SessionError = void 0;
+/**
+ * Error thrown when session operations fail.
+ */
+class SessionError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'SessionError';
+    }
+}
+exports.SessionError = SessionError;
+/**
+ * Session error codes.
+ */
+var SessionErrorCode;
+(function (SessionErrorCode) {
+    /** Session ID not provided */
+    SessionErrorCode["MISSING_SESSION_ID"] = "MISSING_SESSION_ID";
+    /** State file already exists */
+    SessionErrorCode["SESSION_EXISTS"] = "SESSION_EXISTS";
+    /** State file not found */
+    SessionErrorCode["SESSION_NOT_FOUND"] = "SESSION_NOT_FOUND";
+    /** Run already associated */
+    SessionErrorCode["RUN_ALREADY_ASSOCIATED"] = "RUN_ALREADY_ASSOCIATED";
+    /** Run not found */
+    SessionErrorCode["RUN_NOT_FOUND"] = "RUN_NOT_FOUND";
+    /** Run already completed */
+    SessionErrorCode["RUN_COMPLETED"] = "RUN_COMPLETED";
+    /** State file corrupted */
+    SessionErrorCode["CORRUPTED_STATE"] = "CORRUPTED_STATE";
+    /** Invalid state value */
+    SessionErrorCode["INVALID_STATE_VALUE"] = "INVALID_STATE_VALUE";
+    /** File system error */
+    SessionErrorCode["FS_ERROR"] = "FS_ERROR";
+})(SessionErrorCode || (exports.SessionErrorCode = SessionErrorCode = {}));

package/dist/session/write.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Session state file writing utilities.
+ * Provides atomic writes for session state files.
+ */
+import type { SessionState } from './types';
+/**
+ * Serialize session state to YAML frontmatter format.
+ */
+export declare function serializeSessionState(state: SessionState): string;
+/**
+ * Create full session file content with YAML frontmatter and prompt.
+ */
+export declare function createSessionFileContent(state: SessionState, prompt: string): string;
+/**
+ * Write session state file atomically.
+ * Uses temp file + rename pattern to ensure atomic writes.
+ */
+export declare function writeSessionFile(filePath: string, state: SessionState, prompt: string): Promise<void>;
+/**
+ * Update specific fields in an existing session state file.
+ * Reads, modifies, and atomically writes the file.
+ */
+export declare function updateSessionState(filePath: string, updates: Partial<SessionState>, existingContent?: {
+    state: SessionState;
+    prompt: string;
+}): Promise<SessionState>;
+/**
+ * Bind a new run to the session, retiring the previous active run to history.
+ *
+ * Invariant: only one run is active at a time (`runId`).
+ * The previous `runId` (if any) is pushed into `runIds` as audit history.
+ * Idempotent: re-binding the same runId is a no-op.
+ *
+ * Throws if the caller tries to bind a new run while `runId` is still set
+ * and `retirePrevious` is not explicitly true — this forces callers to
+ * acknowledge that the prior run is done.
+ */
+export declare function addRunToSession(state: SessionState, runId: string, options?: {
+    retirePrevious?: boolean;
+}): SessionState;
+/**
+ * Get the historical audit trail of all run IDs for this session (GAP-SESSION-001).
+ * Falls back to [runId] when runIds is empty for backward compatibility
+ * with sessions created before the runIds field existed.
+ */
+export declare function getSessionRuns(state: SessionState): string[];
+/**
+ * Get current ISO timestamp.
+ */
+export declare function getCurrentTimestamp(): string;
+/**
+ * Convert ISO timestamp to epoch seconds.
+ * Returns null if conversion fails.
+ */
+export declare function isoToEpochSeconds(isoTimestamp: string): number | null;
+/**
+ * Calculate iteration duration and update times array.
+ * Keeps only the last 10 durations for diagnostics.
+ */
+export declare function updateIterationTimes(existingTimes: number[], lastIterationAt: string, currentTime: string): number[];
+//# sourceMappingURL=write.d.ts.map

package/dist/session/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/session/write.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG5C;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAgBjE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGpF;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,EAC9B,eAAe,CAAC,EAAE;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxD,OAAO,CAAC,YAAY,CAAC,CAyBvB;AAGD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAA;CAAE,GACrC,YAAY,CAyBd;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE,CAG5D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASrE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,MAAM,EAAE,EACvB,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,GAClB,MAAM,EAAE,CAgBV"}

package/dist/session/write.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Session state file writing utilities.
+ * Provides atomic writes for session state files.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeSessionState = serializeSessionState;
+exports.createSessionFileContent = createSessionFileContent;
+exports.writeSessionFile = writeSessionFile;
+exports.updateSessionState = updateSessionState;
+exports.addRunToSession = addRunToSession;
+exports.getSessionRuns = getSessionRuns;
+exports.getCurrentTimestamp = getCurrentTimestamp;
+exports.isoToEpochSeconds = isoToEpochSeconds;
+exports.updateIterationTimes = updateIterationTimes;
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const types_1 = require("./types");
+/**
+ * Serialize session state to YAML frontmatter format.
+ */
+function serializeSessionState(state) {
+    const lines = [];
+    lines.push(`active: ${state.active}`);
+    lines.push(`iteration: ${state.iteration}`);
+    lines.push(`max_iterations: ${state.maxIterations}`);
+    lines.push(`run_id: "${state.runId}"`);
+    lines.push(`run_ids: ${state.runIds.join(',')}`);
+    lines.push(`started_at: "${state.startedAt}"`);
+    lines.push(`last_iteration_at: "${state.lastIterationAt}"`);
+    lines.push(`iteration_times: ${state.iterationTimes.join(',')}`);
+    for (const [key, value] of Object.entries(state.metadata ?? {})) {
+        lines.push(`metadata_${key}: "${String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Create full session file content with YAML frontmatter and prompt.
+ */
+function createSessionFileContent(state, prompt) {
+    const frontmatter = serializeSessionState(state);
+    return `---\n${frontmatter}\n---\n\n${prompt}\n`;
+}
+/**
+ * Write session state file atomically.
+ * Uses temp file + rename pattern to ensure atomic writes.
+ */
+async function writeSessionFile(filePath, state, prompt) {
+    const content = createSessionFileContent(state, prompt);
+    const dir = path.dirname(filePath);
+    const tempPath = `${filePath}.tmp.${process.pid}`;
+    try {
+        // Ensure directory exists
+        await node_fs_1.promises.mkdir(dir, { recursive: true });
+        // Write to temp file
+        await node_fs_1.promises.writeFile(tempPath, content, 'utf8');
+        // Atomic rename
+        await node_fs_1.promises.rename(tempPath, filePath);
+    }
+    catch (error) {
+        // Clean up temp file on error
+        try {
+            await node_fs_1.promises.unlink(tempPath);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        const err = error;
+        throw new types_1.SessionError(`Failed to write session state file: ${err.message}`, types_1.SessionErrorCode.FS_ERROR, { filePath, originalError: err.message });
+    }
+}
+/**
+ * Update specific fields in an existing session state file.
+ * Reads, modifies, and atomically writes the file.
+ */
+async function updateSessionState(filePath, updates, existingContent) {
+    let state;
+    let prompt;
+    if (existingContent) {
+        state = existingContent.state;
+        prompt = existingContent.prompt;
+    }
+    else {
+        // Read existing file
+        const { readSessionFile } = await Promise.resolve().then(() => __importStar(require('./parse')));
+        const file = await readSessionFile(filePath);
+        state = file.state;
+        prompt = file.prompt;
+    }
+    // Apply updates
+    const updatedState = {
+        ...state,
+        ...updates,
+    };
+    // Write updated file
+    await writeSessionFile(filePath, updatedState, prompt);
+    return updatedState;
+}
+/**
+ * Bind a new run to the session, retiring the previous active run to history.
+ *
+ * Invariant: only one run is active at a time (`runId`).
+ * The previous `runId` (if any) is pushed into `runIds` as audit history.
+ * Idempotent: re-binding the same runId is a no-op.
+ *
+ * Throws if the caller tries to bind a new run while `runId` is still set
+ * and `retirePrevious` is not explicitly true — this forces callers to
+ * acknowledge that the prior run is done.
+ */
+function addRunToSession(state, runId, options) {
+    // Idempotent: already bound to this run
+    if (state.runId === runId)
+        return state;
+    // Guard: refuse to silently overwrite an active run
+    if (state.runId && !options?.retirePrevious) {
+        throw new types_1.SessionError(`Session already bound to run ${state.runId}. ` +
+            `Pass { retirePrevious: true } to retire it and bind ${runId}.`, types_1.SessionErrorCode.RUN_ALREADY_ASSOCIATED, { currentRunId: state.runId, requestedRunId: runId });
+    }
+    // Retire the old runId into history (if not already there)
+    const runIds = [...state.runIds];
+    if (state.runId && !runIds.includes(state.runId)) {
+        runIds.push(state.runId);
+    }
+    // Add the new one to the audit trail too
+    if (!runIds.includes(runId)) {
+        runIds.push(runId);
+    }
+    return { ...state, runId, runIds };
+}
+/**
+ * Get the historical audit trail of all run IDs for this session (GAP-SESSION-001).
+ * Falls back to [runId] when runIds is empty for backward compatibility
+ * with sessions created before the runIds field existed.
+ */
+function getSessionRuns(state) {
+    if (state.runIds.length > 0)
+        return state.runIds;
+    return state.runId ? [state.runId] : [];
+}
+/**
+ * Get current ISO timestamp.
+ */
+function getCurrentTimestamp() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+/**
+ * Convert ISO timestamp to epoch seconds.
+ * Returns null if conversion fails.
+ */
+function isoToEpochSeconds(isoTimestamp) {
+    if (!isoTimestamp)
+        return null;
+    try {
+        const date = new Date(isoTimestamp);
+        if (Number.isNaN(date.getTime()))
+            return null;
+        return Math.floor(date.getTime() / 1000);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Calculate iteration duration and update times array.
+ * Keeps only the last 10 durations for diagnostics.
+ */
+function updateIterationTimes(existingTimes, lastIterationAt, currentTime) {
+    const lastEpoch = isoToEpochSeconds(lastIterationAt);
+    const currentEpoch = isoToEpochSeconds(currentTime);
+    if (lastEpoch === null || currentEpoch === null) {
+        return existingTimes;
+    }
+    const duration = currentEpoch - lastEpoch;
+    if (duration <= 0) {
+        return existingTimes;
+    }
+    const newTimes = [...existingTimes, duration];
+    // Keep only last 10
+    return newTimes.slice(-10);
+}

package/dist/skills/chain.d.ts

@@ -0,0 +1,31 @@
+/**
+ * SkillChainBuilder — assembles an ordered chain of skill invocations with
+ * dependency tracking and topological validation.
+ */
+import type { SkillChain, SkillChainStep } from './types';
+import type { SkillRouter } from './router';
+/**
+ * Build a SkillChain from individual steps, producing a topologically sorted
+ * execution order that respects `dependsOn` declarations.
+ */
+export declare class SkillChainBuilder {
+    private readonly steps;
+    private description;
+    /** Append a step to the chain. */
+    addStep(step: SkillChainStep): this;
+    /** Set the chain's human-readable description. */
+    setDescription(description: string): this;
+    /**
+     * Build the chain, topologically sorting steps so that every step appears
+     * after all of its `dependsOn` prerequisites.
+     *
+     * Throws if the dependency graph contains a cycle.
+     */
+    build(): SkillChain;
+    /**
+     * Validate that every skill referenced in the chain is registered in the
+     * given router. Returns an array of missing skill names (empty = valid).
+     */
+    validate(router: SkillRouter): string[];
+}
+//# sourceMappingURL=chain.d.ts.map

package/dist/skills/chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.d.ts","sourceRoot":"","sources":["../../src/skills/chain.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAC9C,OAAO,CAAC,WAAW,CAAM;IAEzB,kCAAkC;IAClC,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAKnC,kDAAkD;IAClD,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAKzC;;;;;OAKG;IACH,KAAK,IAAI,UAAU;IAQnB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE;CASxC"}

package/dist/skills/chain.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * SkillChainBuilder — assembles an ordered chain of skill invocations with
+ * dependency tracking and topological validation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillChainBuilder = void 0;
+/**
+ * Build a SkillChain from individual steps, producing a topologically sorted
+ * execution order that respects `dependsOn` declarations.
+ */
+class SkillChainBuilder {
+    steps = [];
+    description = '';
+    /** Append a step to the chain. */
+    addStep(step) {
+        this.steps.push(step);
+        return this;
+    }
+    /** Set the chain's human-readable description. */
+    setDescription(description) {
+        this.description = description;
+        return this;
+    }
+    /**
+     * Build the chain, topologically sorting steps so that every step appears
+     * after all of its `dependsOn` prerequisites.
+     *
+     * Throws if the dependency graph contains a cycle.
+     */
+    build() {
+        const sorted = topologicalSort(this.steps);
+        return {
+            steps: sorted,
+            description: this.description,
+        };
+    }
+    /**
+     * Validate that every skill referenced in the chain is registered in the
+     * given router. Returns an array of missing skill names (empty = valid).
+     */
+    validate(router) {
+        const missing = [];
+        for (const step of this.steps) {
+            if (!router.get(step.skillName)) {
+                missing.push(step.skillName);
+            }
+        }
+        return missing;
+    }
+}
+exports.SkillChainBuilder = SkillChainBuilder;
+// ---- topological sort (Kahn's algorithm) ----
+function topologicalSort(steps) {
+    const byName = new Map();
+    for (const step of steps) {
+        byName.set(step.skillName, step);
+    }
+    // Build adjacency and in-degree structures
+    const inDegree = new Map();
+    const dependents = new Map(); // prerequisite -> list of dependents
+    for (const step of steps) {
+        if (!inDegree.has(step.skillName)) {
+            inDegree.set(step.skillName, 0);
+        }
+        if (step.dependsOn) {
+            for (const dep of step.dependsOn) {
+                inDegree.set(step.skillName, (inDegree.get(step.skillName) ?? 0) + 1);
+                const list = dependents.get(dep) ?? [];
+                list.push(step.skillName);
+                dependents.set(dep, list);
+                // Ensure dep has an in-degree entry even if it wasn't added as a step
+                if (!inDegree.has(dep)) {
+                    inDegree.set(dep, 0);
+                }
+            }
+        }
+    }
+    // Collect nodes with in-degree 0
+    const queue = [];
+    for (const [name, degree] of inDegree) {
+        if (degree === 0) {
+            queue.push(name);
+        }
+    }
+    // Stable ordering: sort the initial queue alphabetically
+    queue.sort();
+    const sorted = [];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const step = byName.get(current);
+        if (step) {
+            sorted.push(step);
+        }
+        for (const dependent of dependents.get(current) ?? []) {
+            const newDegree = (inDegree.get(dependent) ?? 1) - 1;
+            inDegree.set(dependent, newDegree);
+            if (newDegree === 0) {
+                queue.push(dependent);
+                queue.sort(); // keep stable ordering
+            }
+        }
+    }
+    // If we didn't visit every step, there's a cycle
+    if (sorted.length < steps.length) {
+        const visited = new Set(sorted.map((s) => s.skillName));
+        const cycleMembers = steps
+            .filter((s) => !visited.has(s.skillName))
+            .map((s) => s.skillName);
+        throw new Error(`Dependency cycle detected among skills: ${cycleMembers.join(', ')}`);
+    }
+    return sorted;
+}

package/dist/skills/discovery.d.ts

@@ -0,0 +1,34 @@
+/**
+ * SkillDiscoveryService — scans directories for SKILL.md files, parses
+ * frontmatter, and converts them to SkillDescriptor instances for the router.
+ */
+import type { SkillDescriptor } from './types';
+/** Raw parsed representation from a SKILL.md file before normalization. */
+export interface RawSkillEntry {
+    name: string;
+    description: string;
+    capabilities: string[];
+    triggers: string[];
+    domain: string | undefined;
+    filePath: string;
+    frontmatter: Record<string, unknown>;
+}
+export declare class SkillDiscoveryService {
+    /**
+     * Parse a single SKILL.md file into a RawSkillEntry.
+     */
+    parseSkillFile(filePath: string): RawSkillEntry;
+    /**
+     * Convert a RawSkillEntry (or any raw-shaped object) to a SkillDescriptor.
+     */
+    toDescriptor(raw: RawSkillEntry, source?: SkillDescriptor['source']): SkillDescriptor;
+    /**
+     * Scan a single directory tree for SKILL.md files and return descriptors.
+     */
+    discoverLocal(dir: string): SkillDescriptor[];
+    /**
+     * Scan multiple plugin directories and return descriptors with source='plugin'.
+     */
+    discoverPlugins(dirs: string[]): SkillDescriptor[];
+}
+//# sourceMappingURL=discovery.d.ts.map

package/dist/skills/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/skills/discovery.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AA0HD,qBAAa,qBAAqB;IAChC;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa;IAgC/C;;OAEG;IACH,YAAY,CACV,GAAG,EAAE,aAAa,EAClB,MAAM,GAAE,eAAe,CAAC,QAAQ,CAAW,GAC1C,eAAe;IAYlB;;OAEG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,EAAE;IAM7C;;OAEG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,EAAE;CAWnD"}