@runcore-sh/runcore 0.1.2

package/dist/avatar/sidecar.js

@@ -0,0 +1,125 @@
+/**
+ * Avatar sidecar lifecycle manager.
+ * Spawns the MuseTalk FastAPI server and monitors its health.
+ * Graceful degradation — if MuseTalk isn't installed, Core falls back to TalkingHead/placeholder.
+ */
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { getAvatarConfig } from "../settings.js";
+import { checkAvatarSidecar } from "./client.js";
+import { createLogger } from "../utils/logger.js";
+const log = createLogger("avatar-sidecar");
+const HEALTH_POLL_INTERVAL = 1000; // ms
+const HEALTH_POLL_TIMEOUT = 60_000; // ms — model loading is slow on first run
+let sidecarProcess = null;
+let available = false;
+function pythonCommand() {
+    // Use the MuseTalk venv Python if it exists (has all the right deps)
+    const config = getAvatarConfig();
+    if (config.musetalkPath) {
+        const venvPython = process.platform === "win32"
+            ? join(config.musetalkPath, ".venv", "Scripts", "python.exe")
+            : join(config.musetalkPath, ".venv", "bin", "python");
+        return venvPython;
+    }
+    return process.platform === "win32" ? "python" : "python3";
+}
+/**
+ * Start the MuseTalk avatar sidecar.
+ * Verifies the MuseTalk path exists, spawns the FastAPI server, polls for health.
+ * Returns true if sidecar is available after startup.
+ */
+export async function startAvatarSidecar() {
+    const config = getAvatarConfig();
+    if (!config.enabled) {
+        available = false;
+        return false;
+    }
+    if (!config.musetalkPath) {
+        log.info(" No musetalkPath configured — avatar disabled");
+        available = false;
+        return false;
+    }
+    // Check if already running externally
+    if (await checkAvatarSidecar()) {
+        available = true;
+        return true;
+    }
+    // Verify MuseTalk path exists
+    try {
+        await access(config.musetalkPath);
+    }
+    catch {
+        log.info(` MuseTalk path not found: ${config.musetalkPath}`);
+        available = false;
+        return false;
+    }
+    const python = pythonCommand();
+    const port = String(config.port);
+    const serverScript = join(process.cwd(), "sidecar", "avatar", "server.py");
+    try {
+        sidecarProcess = spawn(python, [serverScript, "--port", port, "--musetalk-path", config.musetalkPath], {
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: false,
+            env: { ...process.env, PYTHONUTF8: "1", PYTHONIOENCODING: "utf-8" },
+        });
+        sidecarProcess.stdout?.on("data", (data) => {
+            const msg = data.toString().trim();
+            if (msg)
+                log.info(` ${msg}`);
+        });
+        sidecarProcess.stderr?.on("data", (data) => {
+            const msg = data.toString().trim();
+            if (msg)
+                log.info(` ${msg}`);
+        });
+        sidecarProcess.on("error", (err) => {
+            log.info(` Failed to start: ${err.message}`);
+            available = false;
+            sidecarProcess = null;
+        });
+        sidecarProcess.on("exit", (code) => {
+            if (code !== null && code !== 0) {
+                log.info(` Exited with code ${code}`);
+            }
+            available = false;
+            sidecarProcess = null;
+        });
+        // Poll until ready or timeout
+        const start = Date.now();
+        while (Date.now() - start < HEALTH_POLL_TIMEOUT) {
+            if (await checkAvatarSidecar()) {
+                available = true;
+                return true;
+            }
+            await new Promise((r) => setTimeout(r, HEALTH_POLL_INTERVAL));
+        }
+        log.info(" Timed out waiting for health check");
+        stopAvatarSidecar();
+        return false;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.info(` Spawn failed: ${msg}`);
+        return false;
+    }
+}
+/** Check if the avatar sidecar is currently available. */
+export function isAvatarAvailable() {
+    return available;
+}
+/** Stop the avatar sidecar process. */
+export function stopAvatarSidecar() {
+    if (sidecarProcess) {
+        try {
+            sidecarProcess.kill();
+        }
+        catch {
+            // Already dead
+        }
+        sidecarProcess = null;
+    }
+    available = false;
+}
+//# sourceMappingURL=sidecar.js.map

package/dist/avatar/sidecar.js.map

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

package/dist/board/provider.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Board provider registry.
+ * Holds the active provider and exposes it to server routes / chat commands.
+ * Providers register themselves at startup; only one is active at a time.
+ */
+import type { BoardProvider } from "./types.js";
+/** Set the active board provider (called at startup). */
+export declare function setBoardProvider(provider: BoardProvider): void;
+/** Get the active board provider, or null if none registered. */
+export declare function getBoardProvider(): BoardProvider | null;
+/** Convenience: is any board provider available and configured? */
+export declare function isBoardAvailable(): boolean;
+//# sourceMappingURL=provider.d.ts.map

package/dist/board/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/board/provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD,yDAAyD;AACzD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAE9D;AAED,iEAAiE;AACjE,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,IAAI,CAEvD;AAED,mEAAmE;AACnE,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C"}

package/dist/board/provider.js

@@ -0,0 +1,19 @@
+/**
+ * Board provider registry.
+ * Holds the active provider and exposes it to server routes / chat commands.
+ * Providers register themselves at startup; only one is active at a time.
+ */
+let activeProvider = null;
+/** Set the active board provider (called at startup). */
+export function setBoardProvider(provider) {
+    activeProvider = provider;
+}
+/** Get the active board provider, or null if none registered. */
+export function getBoardProvider() {
+    return activeProvider;
+}
+/** Convenience: is any board provider available and configured? */
+export function isBoardAvailable() {
+    return activeProvider !== null && activeProvider.isAvailable();
+}
+//# sourceMappingURL=provider.js.map

package/dist/board/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/board/provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,IAAI,cAAc,GAAyB,IAAI,CAAC;AAEhD,yDAAyD;AACzD,MAAM,UAAU,gBAAgB,CAAC,QAAuB;IACtD,cAAc,GAAG,QAAQ,CAAC;AAC5B,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,gBAAgB;IAC9B,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,gBAAgB;IAC9B,OAAO,cAAc,KAAK,IAAI,IAAI,cAAc,CAAC,WAAW,EAAE,CAAC;AACjE,CAAC"}

package/dist/board/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Generic task board abstraction.
+ * Linear, GitHub Issues, Notion, Jira, etc. all implement BoardProvider.
+ * Server routes and chat commands only talk to this interface.
+ */
+export interface BoardIssue {
+    id: string;
+    identifier: string;
+    title: string;
+    state: string;
+    priority: number;
+    assignee: string | null;
+    project?: string;
+    url: string;
+}
+export interface BoardTeam {
+    id: string;
+    name: string;
+    key: string;
+}
+export interface BoardState {
+    id: string;
+    name: string;
+    type: string;
+    position: number;
+}
+export interface BoardUser {
+    id: string;
+    name: string;
+    email: string;
+    displayName: string;
+}
+export interface BoardProvider {
+    /** Human-readable name for startup banner / UI. */
+    readonly name: string;
+    /** Check if this provider is configured and ready. */
+    isAvailable(): boolean;
+    /** Get the authenticated user. */
+    getMe(): Promise<BoardUser | null>;
+    /** List teams/projects. */
+    getTeams(): Promise<BoardTeam[] | null>;
+    /** List workflow states for a team. */
+    getTeamStates(teamId: string): Promise<BoardState[] | null>;
+    /** List issues, optionally filtered. */
+    listIssues(opts?: {
+        teamId?: string;
+        stateType?: string;
+        limit?: number;
+        excludeAssigned?: boolean;
+    }): Promise<BoardIssue[] | null>;
+    /** Create a new issue. Returns the created issue. */
+    createIssue(title: string, opts?: {
+        description?: string;
+        teamId?: string;
+        assigneeId?: string;
+        priority?: number;
+        labelIds?: string[];
+        project?: string;
+        origin?: "chat" | "agent" | "autonomous" | "external";
+        originSessionId?: string;
+    }): Promise<BoardIssue | null>;
+    /** Update an existing issue. Returns the updated issue. */
+    updateIssue(id: string, opts: {
+        title?: string;
+        stateId?: string;
+        assigneeId?: string;
+        priority?: number;
+    }): Promise<BoardIssue | null>;
+    /** Add a comment to an issue. */
+    addComment(issueId: string, body: string): Promise<boolean>;
+    /** Find issue by its human-readable identifier (e.g. "DASH-12"). */
+    findByIdentifier(identifier: string): Promise<BoardIssue | null>;
+    /** Get the "Done" / completed state ID for a team. */
+    getDoneStateId(teamId: string): Promise<string | null>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/board/types.d.ts.map

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

package/dist/board/types.js

@@ -0,0 +1,7 @@
+/**
+ * Generic task board abstraction.
+ * Linear, GitHub Issues, Notion, Jira, etc. all implement BoardProvider.
+ * Server routes and chat commands only talk to this interface.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/board/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/board/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/brain/skills.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Skill schema validation for Core agent skills.
+ *
+ * Validates `.yml` skill files in `brain/skills/` against the schema
+ * defined in `brain/skills/schema.yml`.
+ *
+ * @example
+ * ```ts
+ * import { validateSkill, parseSkillYaml } from "./brain/skills.js";
+ *
+ * const raw = fs.readFileSync("brain/skills/file-editing.yml", "utf-8");
+ * const parsed = parseSkillYaml(raw);
+ * const result = validateSkill(parsed);
+ *
+ * if (!result.valid) {
+ *   console.error("Validation errors:", result.errors);
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { validateSkillFile } from "./brain/skills.js";
+ *
+ * const result = await validateSkillFile("brain/skills/git-operations.yml");
+ * if (result.valid) {
+ *   console.log("Skill:", result.skill!.name);
+ * }
+ * ```
+ */
+/** A validated skill definition. */
+export interface SkillDefinition {
+    name: string;
+    description: string;
+    tools: string[];
+    context_patterns: string[];
+    example_prompt: string;
+    version?: string;
+    tags?: string[];
+    depends_on?: string[];
+    notes?: string;
+}
+/** Result of validating a skill file. */
+export interface SkillValidationResult {
+    valid: boolean;
+    errors: string[];
+    skill: SkillDefinition | null;
+}
+/**
+ * Parse a flat YAML skill file into a key-value record.
+ *
+ * Handles simple scalars (`key: value`), folded scalars (`key: >`),
+ * and arrays (`key:` + `- item` lines). Not a general-purpose YAML
+ * parser — designed for the specific structure of Core skill files.
+ *
+ * @example
+ * ```ts
+ * const parsed = parseSkillYaml(`
+ * name: my-skill
+ * tools:
+ *   - git
+ *   - npm
+ * description: >
+ *   A multi-line
+ *   description here.
+ * `);
+ * // { name: "my-skill", tools: ["git", "npm"], description: "A multi-line description here." }
+ * ```
+ */
+export declare function parseSkillYaml(content: string): Record<string, string | string[]>;
+/**
+ * Validate a parsed skill object against the Core skill schema.
+ *
+ * Returns `{ valid: true, errors: [], skill }` on success, or
+ * `{ valid: false, errors: [...], skill: null }` with descriptive
+ * error messages for each violation.
+ *
+ * @example
+ * ```ts
+ * const result = validateSkill({ name: "my-skill", description: "Does stuff" });
+ * // { valid: false, errors: ["Missing required field: tools", ...], skill: null }
+ * ```
+ */
+export declare function validateSkill(data: Record<string, unknown>): SkillValidationResult;
+/**
+ * Read and validate a skill YAML file from disk.
+ *
+ * Combines parsing and validation in one step. Returns the validated
+ * skill definition or a list of errors.
+ *
+ * @example
+ * ```ts
+ * const result = await validateSkillFile("brain/skills/file-editing.yml");
+ * if (result.valid) {
+ *   console.log(`Loaded skill: ${result.skill!.name}`);
+ *   console.log(`Tools: ${result.skill!.tools.join(", ")}`);
+ * } else {
+ *   for (const err of result.errors) console.error(`  - ${err}`);
+ * }
+ * ```
+ */
+export declare function validateSkillFile(filePath: string): Promise<SkillValidationResult>;
+/** Context passed to matchSkills for relevance scoring. */
+export interface SkillMatchContext {
+    /** File paths involved in the current task. */
+    filePaths?: string[];
+    /** Free-text description of what the agent is doing. */
+    content?: string;
+}
+/** A matched skill with its relevance score. */
+export interface SkillMatch {
+    skill: SkillDefinition;
+    /** Relevance score (0–1). Higher = more relevant. */
+    score: number;
+    /** Which context_patterns matched. */
+    matchedPatterns: string[];
+}
+/**
+ * Registry for YAML-based brain skills (`brain/skills/*.yml`).
+ *
+ * Loads skill definitions from disk, validates them against the schema,
+ * and provides context-aware matching and prompt formatting for agent
+ * injection.
+ */
+export declare class SkillRegistry {
+    private readonly skillsDir;
+    private readonly skills;
+    private loaded;
+    constructor(skillsDir: string);
+    /**
+     * Load all `.yml` skill files from the skills directory.
+     * Validates each against the schema and registers valid skills.
+     * Skips `schema.yml` itself. Safe to call multiple times — clears
+     * and reloads on subsequent calls.
+     */
+    loadSkills(): Promise<void>;
+    /**
+     * Match skills against a task context.
+     *
+     * Scores each skill by checking its `context_patterns` against the
+     * provided file paths (glob-style prefix/suffix matching) and content
+     * keywords (case-insensitive substring matching).
+     *
+     * Returns matches sorted by score descending. Skills with no matches
+     * are excluded.
+     */
+    matchSkills(context: SkillMatchContext): SkillMatch[];
+    /**
+     * Format a skill for injection into an agent prompt.
+     *
+     * Returns a structured block with the skill name, description, tools,
+     * example prompt, and notes — ready for inclusion in an LLM system
+     * message. Returns null if the skill is not found.
+     */
+    getSkillPrompt(skillName: string): string | null;
+    /** Get a skill by name. */
+    get(name: string): SkillDefinition | undefined;
+    /** Check if a skill is registered. */
+    has(name: string): boolean;
+    /** List all loaded skill names. */
+    list(): string[];
+    /** Total number of loaded skills. */
+    get size(): number;
+    /**
+     * Check whether a context_pattern matches any of the given file paths.
+     *
+     * Supports:
+     *  - Extension patterns (`*.ts`, `*.yml`) — matches file suffix
+     *  - Directory patterns (`src/`, `logs/`) — matches path containing the dir
+     *  - Exact filenames (`CHANGELOG.md`) — matches basename or full path
+     */
+    private patternMatchesPaths;
+    /** Throw if loadSkills() hasn't been called yet. */
+    private ensureLoaded;
+}
+/** Pre-configured singleton for `brain/skills/`. */
+export declare const brainSkillRegistry: SkillRegistry;
+//# sourceMappingURL=skills.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/brain/skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,yCAAyC;AACzC,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;CAC/B;AA2BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,GACd,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CA4EnC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,qBAAqB,CA8FvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,qBAAqB,CAAC,CAgBhC;AAMD,2DAA2D;AAC3D,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,gDAAgD;AAChD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,eAAe,CAAC;IACvB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAMD;;;;;;GAMG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAC7D,OAAO,CAAC,MAAM,CAAS;gBAEX,SAAS,EAAE,MAAM;IAI7B;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA+CjC;;;;;;;;;OASG;IACH,WAAW,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,EAAE;IAsCrD;;;;;;OAMG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAmChD,2BAA2B;IAC3B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAK9C,sCAAsC;IACtC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAK1B,mCAAmC;IACnC,IAAI,IAAI,MAAM,EAAE;IAKhB,qCAAqC;IACrC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAMD;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IA6B3B,oDAAoD;IACpD,OAAO,CAAC,YAAY;CAOrB;AAMD,oDAAoD;AACpD,eAAO,MAAM,kBAAkB,eAAoC,CAAC"}