@alpacakit/agents 0.1.0-beta.19

package/dist/fleet/store.js

@@ -0,0 +1,225 @@
+/**
+ * Fleet state store port (design A4/A5): cooldowns keyed by candidate
+ * identity, sticky auth marks keyed by profile id. Expiry is purely
+ * time-based and evaluated by the fleet, not the store. The file
+ * implementation writes atomically (temp + rename) under an advisory
+ * cross-process lock with 0700/0600 modes. Fleet state is a cache:
+ * unknown versions are discarded and reconstructed from future runs.
+ */
+import { mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { AGENT_ERROR_CODE, AgentError } from "../core/error.js";
+import { isErrnoCode, PRIVATE_DIRECTORY_MODE, PRIVATE_FILE_MODE, writeFileAtomically, } from "../core/fs.js";
+import { systemClock } from "../core/node-ports.js";
+import { TEXT_ENCODING } from "../core/values.js";
+class MemoryFleetStateStore {
+    cooldowns = new Map();
+    authInvalid = new Set();
+    getCooldownUntil(key) {
+        return Promise.resolve(this.cooldowns.get(key) ?? null);
+    }
+    setCooldownUntil(key, untilIso) {
+        this.cooldowns.set(key, untilIso);
+        return Promise.resolve();
+    }
+    isAuthInvalid(profileId) {
+        return Promise.resolve(this.authInvalid.has(profileId));
+    }
+    markAuthInvalid(profileId) {
+        this.authInvalid.add(profileId);
+        return Promise.resolve();
+    }
+}
+const FLEET_STATE_FILE_VERSION = 1;
+const EXCLUSIVE_CREATE_FLAG = "wx";
+const LOCK_FILE_SUFFIX = "lock";
+const STALE_LOCK_SUFFIX = "stale";
+const EMPTY_STATE = {
+    version: FLEET_STATE_FILE_VERSION,
+    cooldowns: {},
+    authInvalid: [],
+};
+const LOCK_STALE_MS = 30_000;
+const LOCK_RETRY_MS = 10;
+const LOCK_MAX_ATTEMPTS = 300;
+const sleep = (clock, ms) => new Promise((resolve) => {
+    clock.setTimeout(resolve, ms);
+});
+async function isStaleLock(lockPath, clock) {
+    try {
+        const info = await stat(lockPath);
+        return clock.now() - info.mtimeMs > LOCK_STALE_MS;
+    }
+    catch {
+        return false;
+    }
+}
+let staleTakeoverSequence = 0;
+/**
+ * Single-winner stale-lock takeover: rename the stale lock to a name
+ * only this contender uses, then remove the renamed file. Rename is
+ * atomic, so of several waiters that observed the same stale lock
+ * exactly one wins; losers see ENOENT and re-enter the acquire loop
+ * instead of deleting whatever (possibly fresh) lock now sits there.
+ */
+async function takeOverStaleLock(lockPath) {
+    staleTakeoverSequence += 1;
+    const stalePath = [
+        lockPath,
+        STALE_LOCK_SUFFIX,
+        String(process.pid),
+        String(staleTakeoverSequence),
+    ].join(".");
+    try {
+        await rename(lockPath, stalePath);
+    }
+    catch (error) {
+        if (isErrnoCode(error, "ENOENT")) {
+            // Another contender already took the stale lock over.
+            return;
+        }
+        throw new AgentError({
+            code: AGENT_ERROR_CODE.failed,
+            message: `Could not take over stale fleet store lock: ${lockPath}`,
+            data: { exitCode: null, stdoutTail: null, stderrTail: null },
+            cause: error,
+        });
+    }
+    await rm(stalePath, { force: true });
+}
+async function withFileLock(filePath, clock, task) {
+    await mkdir(path.dirname(filePath), {
+        recursive: true,
+        mode: PRIVATE_DIRECTORY_MODE,
+    });
+    const lockPath = [filePath, LOCK_FILE_SUFFIX].join(".");
+    let locked = false;
+    for (let attempt = 0; attempt < LOCK_MAX_ATTEMPTS; attempt += 1) {
+        try {
+            const handle = await open(lockPath, EXCLUSIVE_CREATE_FLAG, PRIVATE_FILE_MODE);
+            try {
+                // Record the owning pid for post-mortem debugging of stale locks.
+                await handle.writeFile(`${process.pid}\n`, TEXT_ENCODING);
+            }
+            finally {
+                await handle.close();
+            }
+            locked = true;
+            break;
+        }
+        catch (error) {
+            if (!isErrnoCode(error, "EEXIST")) {
+                // Not lock contention (permissions, read-only fs, ...): retrying
+                // cannot help, so fail immediately with the real cause.
+                throw new AgentError({
+                    code: AGENT_ERROR_CODE.failed,
+                    message: `Could not create fleet store lock: ${lockPath}`,
+                    data: { exitCode: null, stdoutTail: null, stderrTail: null },
+                    cause: error,
+                });
+            }
+            if (await isStaleLock(lockPath, clock)) {
+                await takeOverStaleLock(lockPath);
+                continue;
+            }
+            if (attempt === LOCK_MAX_ATTEMPTS - 1) {
+                throw new AgentError({
+                    code: AGENT_ERROR_CODE.failed,
+                    message: `Timed out waiting for fleet store lock: ${lockPath}`,
+                    data: { exitCode: null, stdoutTail: null, stderrTail: null },
+                    cause: error,
+                });
+            }
+            await sleep(clock, LOCK_RETRY_MS);
+        }
+    }
+    try {
+        return await task();
+    }
+    finally {
+        if (locked) {
+            await rm(lockPath, { force: true });
+        }
+    }
+}
+async function loadState(filePath) {
+    let raw;
+    try {
+        raw = await readFile(filePath, TEXT_ENCODING);
+    }
+    catch {
+        return structuredClone(EMPTY_STATE);
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null) {
+            return structuredClone(EMPTY_STATE);
+        }
+        const record = parsed;
+        if (record.version !== FLEET_STATE_FILE_VERSION) {
+            return structuredClone(EMPTY_STATE);
+        }
+        return {
+            version: FLEET_STATE_FILE_VERSION,
+            cooldowns: typeof record.cooldowns === "object" && record.cooldowns !== null
+                ? record.cooldowns
+                : {},
+            authInvalid: Array.isArray(record.authInvalid) ? record.authInvalid : [],
+        };
+    }
+    catch {
+        return structuredClone(EMPTY_STATE);
+    }
+}
+async function saveState(filePath, state) {
+    await writeFileAtomically(filePath, `${JSON.stringify(state, null, 2)}\n`);
+}
+class FileFleetStateStore {
+    filePath;
+    clock;
+    // Serialize mutations so concurrent fleet attempts cannot interleave
+    // read-modify-write cycles within this process.
+    queue = Promise.resolve();
+    constructor(filePath, clock) {
+        this.filePath = filePath;
+        this.clock = clock;
+    }
+    getCooldownUntil(key) {
+        return this.enqueue(async () => (await loadState(this.filePath)).cooldowns[key] ?? null);
+    }
+    setCooldownUntil(key, untilIso) {
+        return this.enqueue(() => withFileLock(this.filePath, this.clock, async () => {
+            const state = await loadState(this.filePath);
+            state.cooldowns[key] = untilIso;
+            await saveState(this.filePath, state);
+        }));
+    }
+    isAuthInvalid(profileId) {
+        return this.enqueue(async () => (await loadState(this.filePath)).authInvalid.includes(profileId));
+    }
+    markAuthInvalid(profileId) {
+        return this.enqueue(() => withFileLock(this.filePath, this.clock, async () => {
+            const state = await loadState(this.filePath);
+            if (!state.authInvalid.includes(profileId)) {
+                state.authInvalid.push(profileId);
+                await saveState(this.filePath, state);
+            }
+        }));
+    }
+    enqueue(task) {
+        const next = this.queue.then(task);
+        this.queue = next.catch(() => { });
+        return next;
+    }
+}
+export function memoryFleetStore() {
+    return new MemoryFleetStateStore();
+}
+/**
+ * Lock retry pacing and stale-lock age both read the injected clock
+ * (inbound, rule 1: absent = production system clock) so contention and
+ * takeover are testable without real waiting.
+ */
+export function fileFleetStore(filePath, clock) {
+    return new FileFleetStateStore(filePath, clock ?? systemClock);
+}

package/dist/host/capabilities.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Host-plane capability contracts (design "Skills and MCP"). Keyed
+ * handler records per source kind / transport: presence = supported,
+ * absence = typed unsupported. Concrete implementations live on each
+ * adapter; the contracts and shared spec types live here.
+ */
+import type { HostContext } from "./context.js";
+export declare const SKILL_SOURCE_KIND: {
+    readonly localDir: "local-dir";
+    readonly githubDir: "github-dir";
+    readonly plugin: "plugin";
+};
+export type SkillSource = {
+    kind: typeof SKILL_SOURCE_KIND.localDir;
+    path: string;
+} | {
+    kind: typeof SKILL_SOURCE_KIND.githubDir;
+    repo: string;
+    ref: string;
+    path: string;
+} | {
+    kind: typeof SKILL_SOURCE_KIND.plugin;
+    name: string;
+};
+export type SkillSourceKind = SkillSource["kind"];
+export type InstalledSkill = {
+    id: string;
+    name: string;
+    description: string;
+    location: string;
+    source: string;
+};
+export type InstallOptions = {
+    overwrite?: boolean;
+};
+export declare const INSTALL_STATUS: {
+    readonly installed: "installed";
+    readonly alreadyInstalled: "already-installed";
+};
+export type InstallOutcome = {
+    status: typeof INSTALL_STATUS.installed;
+    location: string;
+} | {
+    status: typeof INSTALL_STATUS.alreadyInstalled;
+    location: string;
+};
+export interface SkillsCapability {
+    list(ctx: HostContext): Promise<InstalledSkill[]>;
+    install: {
+        [K in SkillSourceKind]?: (ctx: HostContext, source: Extract<SkillSource, {
+            kind: K;
+        }>, options: InstallOptions) => Promise<InstallOutcome>;
+    };
+}
+export declare const MCP_TRANSPORT: {
+    readonly stdio: "stdio";
+    readonly http: "http";
+};
+export type McpServerSpec = {
+    transport: typeof MCP_TRANSPORT.stdio;
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    cwd: string | null;
+} | {
+    transport: typeof MCP_TRANSPORT.http;
+    url: string;
+    bearerTokenEnvVar: string | null;
+    headers: Record<string, string>;
+};
+export type McpTransport = McpServerSpec["transport"];
+export type StdioMcpServerSpec = Extract<McpServerSpec, {
+    transport: typeof MCP_TRANSPORT.stdio;
+}>;
+export declare const MCP_SCOPE: {
+    readonly project: "project";
+    readonly user: "user";
+};
+export type McpScope = (typeof MCP_SCOPE)[keyof typeof MCP_SCOPE];
+export type McpServerState = {
+    name: string;
+    transport: McpTransport;
+    usable: boolean;
+    /** `null` when the CLI did not enumerate tools (unknown, not "none"). */
+    tools: readonly string[] | null;
+};
+export interface McpCapability {
+    list(ctx: HostContext): Promise<McpServerState[]>;
+    add: {
+        [T in McpTransport]?: (ctx: HostContext, name: string, spec: Extract<McpServerSpec, {
+            transport: T;
+        }>, options: {
+            scope: McpScope;
+        }) => Promise<InstallOutcome>;
+    };
+    remove(ctx: HostContext, name: string, options: {
+        scope: McpScope;
+    }): Promise<void>;
+}
+export declare const DOCTOR_CHECK_STATUS: {
+    readonly pass: "pass";
+    readonly fail: "fail";
+};
+export type DoctorCheck = {
+    id: string;
+    status: (typeof DOCTOR_CHECK_STATUS)[keyof typeof DOCTOR_CHECK_STATUS];
+    detail: string | null;
+};
+export type DoctorReport = {
+    available: boolean;
+    checks: DoctorCheck[];
+};
+export interface DoctorCapability {
+    probe(ctx: HostContext): Promise<DoctorReport>;
+}
+export declare const CAPABILITY_AVAILABILITY_STATUS: {
+    readonly available: "available";
+    readonly missing: "missing";
+    readonly unusable: "unusable";
+    readonly toolMissing: "tool-missing";
+};
+export type SkillAvailability = {
+    status: typeof CAPABILITY_AVAILABILITY_STATUS.available;
+    skill: InstalledSkill;
+} | {
+    status: typeof CAPABILITY_AVAILABILITY_STATUS.missing;
+};
+export type McpAvailability = {
+    status: typeof CAPABILITY_AVAILABILITY_STATUS.available;
+    server: McpServerState;
+} | {
+    status: typeof CAPABILITY_AVAILABILITY_STATUS.missing;
+} | {
+    status: typeof CAPABILITY_AVAILABILITY_STATUS.unusable;
+    server: McpServerState;
+} | {
+    status: typeof CAPABILITY_AVAILABILITY_STATUS.toolMissing;
+    server: McpServerState;
+    tool: string;
+};
+export declare function checkSkillAvailability(skills: readonly InstalledSkill[], id: string): SkillAvailability;
+export declare function checkMcpAvailability(servers: readonly McpServerState[], requirement: {
+    server: string;
+    tool: string | null;
+}): McpAvailability;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/host/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/host/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,eAAO,MAAM,iBAAiB;;;;CAIpB,CAAC;AAEX,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,OAAO,iBAAiB,CAAC,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzD;IACE,IAAI,EAAE,OAAO,iBAAiB,CAAC,SAAS,CAAC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd,GACD;IAAE,IAAI,EAAE,OAAO,iBAAiB,CAAC,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;AAElD,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,cAAc;;;CAGjB,CAAC;AAEX,MAAM,MAAM,cAAc,GACtB;IAAE,MAAM,EAAE,OAAO,cAAc,CAAC,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,MAAM,EAAE,OAAO,cAAc,CAAC,gBAAgB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAClD,OAAO,EAAE;SACN,CAAC,IAAI,eAAe,CAAC,CAAC,EAAE,CACvB,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE;YAAE,IAAI,EAAE,CAAC,CAAA;SAAE,CAAC,EACzC,OAAO,EAAE,cAAc,KACpB,OAAO,CAAC,cAAc,CAAC;KAC7B,CAAC;CACH;AAED,eAAO,MAAM,aAAa;;;CAGhB,CAAC;AAEX,MAAM,MAAM,aAAa,GACrB;IACE,SAAS,EAAE,OAAO,aAAa,CAAC,KAAK,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB,GACD;IACE,SAAS,EAAE,OAAO,aAAa,CAAC,IAAI,CAAC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC,CAAC;AAEN,MAAM,MAAM,YAAY,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;AAEtD,MAAM,MAAM,kBAAkB,GAAG,OAAO,CACtC,aAAa,EACb;IAAE,SAAS,EAAE,OAAO,aAAa,CAAC,KAAK,CAAA;CAAE,CAC1C,CAAC;AAEF,eAAO,MAAM,SAAS;;;CAGZ,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAElE,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,YAAY,CAAC;IACxB,MAAM,EAAE,OAAO,CAAC;IAChB,yEAAyE;IACzE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CACjC,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAClD,GAAG,EAAE;SACF,CAAC,IAAI,YAAY,CAAC,CAAC,EAAE,CACpB,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,CAAC,aAAa,EAAE;YAAE,SAAS,EAAE,CAAC,CAAA;SAAE,CAAC,EAC9C,OAAO,EAAE;YAAE,KAAK,EAAE,QAAQ,CAAA;SAAE,KACzB,OAAO,CAAC,cAAc,CAAC;KAC7B,CAAC;IACF,MAAM,CACJ,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,KAAK,EAAE,QAAQ,CAAA;KAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,eAAO,MAAM,mBAAmB;;;CAGtB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;IACvE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAChD;AAED,eAAO,MAAM,8BAA8B;;;;;CAKjC,CAAC;AAEX,MAAM,MAAM,iBAAiB,GACzB;IACE,MAAM,EAAE,OAAO,8BAA8B,CAAC,SAAS,CAAC;IACxD,KAAK,EAAE,cAAc,CAAC;CACvB,GACD;IAAE,MAAM,EAAE,OAAO,8BAA8B,CAAC,OAAO,CAAA;CAAE,CAAC;AAE9D,MAAM,MAAM,eAAe,GACvB;IACE,MAAM,EAAE,OAAO,8BAA8B,CAAC,SAAS,CAAC;IACxD,MAAM,EAAE,cAAc,CAAC;CACxB,GACD;IAAE,MAAM,EAAE,OAAO,8BAA8B,CAAC,OAAO,CAAA;CAAE,GACzD;IACE,MAAM,EAAE,OAAO,8BAA8B,CAAC,QAAQ,CAAC;IACvD,MAAM,EAAE,cAAc,CAAC;CACxB,GACD;IACE,MAAM,EAAE,OAAO,8BAA8B,CAAC,WAAW,CAAC;IAC1D,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEN,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,EAAE,EAAE,MAAM,GACT,iBAAiB,CAOnB;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,WAAW,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACnD,eAAe,CAqBjB"}

package/dist/host/capabilities.js

@@ -0,0 +1,59 @@
+/**
+ * Host-plane capability contracts (design "Skills and MCP"). Keyed
+ * handler records per source kind / transport: presence = supported,
+ * absence = typed unsupported. Concrete implementations live on each
+ * adapter; the contracts and shared spec types live here.
+ */
+export const SKILL_SOURCE_KIND = {
+    localDir: "local-dir",
+    githubDir: "github-dir",
+    plugin: "plugin",
+};
+export const INSTALL_STATUS = {
+    installed: "installed",
+    alreadyInstalled: "already-installed",
+};
+export const MCP_TRANSPORT = {
+    stdio: "stdio",
+    http: "http",
+};
+export const MCP_SCOPE = {
+    project: "project",
+    user: "user",
+};
+export const DOCTOR_CHECK_STATUS = {
+    pass: "pass",
+    fail: "fail",
+};
+export const CAPABILITY_AVAILABILITY_STATUS = {
+    available: "available",
+    missing: "missing",
+    unusable: "unusable",
+    toolMissing: "tool-missing",
+};
+export function checkSkillAvailability(skills, id) {
+    const skill = skills.find((candidate) => candidate.id === id || candidate.name === id) ??
+        null;
+    return skill === null
+        ? { status: CAPABILITY_AVAILABILITY_STATUS.missing }
+        : { status: CAPABILITY_AVAILABILITY_STATUS.available, skill };
+}
+export function checkMcpAvailability(servers, requirement) {
+    const server = servers.find((candidate) => candidate.name === requirement.server) ?? null;
+    if (server === null) {
+        return { status: CAPABILITY_AVAILABILITY_STATUS.missing };
+    }
+    if (!server.usable) {
+        return { status: CAPABILITY_AVAILABILITY_STATUS.unusable, server };
+    }
+    if (requirement.tool !== null &&
+        server.tools !== null &&
+        !server.tools.includes(requirement.tool)) {
+        return {
+            status: CAPABILITY_AVAILABILITY_STATUS.toolMissing,
+            server,
+            tool: requirement.tool,
+        };
+    }
+    return { status: CAPABILITY_AVAILABILITY_STATUS.available, server };
+}

package/dist/host/context.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Host-plane context (design "Skills and MCP"): the runtime owns the
+ * effectful parts and binds them once; the call site owns locations.
+ * Nothing here ever calls `os.homedir()`.
+ */
+import type { Clock, Exec, HttpClient, Logger } from "../core/ports.js";
+/** Call-site input (rule 1). */
+export type HostLocation = {
+    homeDir: string;
+    projectDir?: string;
+};
+/** What capability implementations receive (rule 2). */
+export type HostContext = {
+    location: {
+        homeDir: string;
+        projectDir: string | null;
+    };
+    env: Record<string, string>;
+    exec: Exec;
+    http: HttpClient;
+    /** For probe-owned time mechanics (timeouts) — mirrors RunContext. */
+    clock: Clock;
+    logger: Logger;
+};
+export declare function resolveHostLocation(location: HostLocation): {
+    homeDir: string;
+    projectDir: string | null;
+};
+//# sourceMappingURL=context.d.ts.map

package/dist/host/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/host/context.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAExE,gCAAgC;AAChC,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACzD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,sEAAsE;IACtE,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAKA"}

package/dist/host/context.js

@@ -0,0 +1,11 @@
+/**
+ * Host-plane context (design "Skills and MCP"): the runtime owns the
+ * effectful parts and binds them once; the call site owns locations.
+ * Nothing here ever calls `os.homedir()`.
+ */
+export function resolveHostLocation(location) {
+    return {
+        homeDir: location.homeDir,
+        projectDir: location.projectDir ?? null,
+    };
+}

package/dist/host/github-dir.d.ts

@@ -0,0 +1,16 @@
+/**
+ * GitHub-directory fetch adapter for skill installation (design v D4):
+ * walk the GitHub contents API over the host `http` port and stage the
+ * directory tree into a temp dir. The staged tree then flows through the
+ * caller's local install pipeline — sources differ only in this fetch
+ * step, never in validation or copy. File contents stay `Buffer` from
+ * fetch to disk so binary assets survive staging byte-for-byte.
+ */
+import type { SKILL_SOURCE_KIND, SkillSource } from "./capabilities.js";
+import type { HostContext } from "./context.js";
+export type GithubDirSource = Extract<SkillSource, {
+    kind: typeof SKILL_SOURCE_KIND.githubDir;
+}>;
+/** Stage the remote directory, hand it to `use`, always clean up. */
+export declare function withStagedGithubDirectory<T>(ctx: HostContext, source: GithubDirSource, use: (stagedDir: string) => Promise<T>): Promise<T>;
+//# sourceMappingURL=github-dir.d.ts.map

package/dist/host/github-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-dir.d.ts","sourceRoot":"","sources":["../../src/host/github-dir.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,MAAM,MAAM,eAAe,GAAG,OAAO,CACnC,WAAW,EACX;IAAE,IAAI,EAAE,OAAO,iBAAiB,CAAC,SAAS,CAAA;CAAE,CAC7C,CAAC;AAqKF,qEAAqE;AACrE,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GACrC,OAAO,CAAC,CAAC,CAAC,CAWZ"}

package/dist/host/github-dir.js

@@ -0,0 +1,164 @@
+/**
+ * GitHub-directory fetch adapter for skill installation (design v D4):
+ * walk the GitHub contents API over the host `http` port and stage the
+ * directory tree into a temp dir. The staged tree then flows through the
+ * caller's local install pipeline — sources differ only in this fetch
+ * step, never in validation or copy. File contents stay `Buffer` from
+ * fetch to disk so binary assets survive staging byte-for-byte.
+ */
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { AGENT_ERROR_CODE, AgentError } from "../core/error.js";
+import { readString, readUnknownRecord, } from "../core/json.js";
+const GITHUB_CONTENTS_API = "https://api.github.com/repos";
+const STAGING_DIRECTORY_PREFIX = "agents-github-skill-";
+const DEFAULT_SKILL_DIRECTORY_NAME = "skill";
+const GITHUB_CONTENTS_FIELD = {
+    content: "content",
+    downloadUrl: "download_url",
+    encoding: "encoding",
+    name: "name",
+    path: "path",
+    type: "type",
+};
+const GITHUB_CONTENTS_ENTRY_TYPE = {
+    directory: "dir",
+    file: "file",
+};
+const GITHUB_CONTENT_ENCODING = {
+    base64: "base64",
+};
+function githubSourceDirectoryName(source) {
+    const normalized = source.path.replace(/\/+$/u, "");
+    if (normalized !== "") {
+        return path.basename(normalized);
+    }
+    const repoName = source.repo.split("/").at(-1);
+    return repoName === undefined || repoName === ""
+        ? DEFAULT_SKILL_DIRECTORY_NAME
+        : repoName;
+}
+function githubRepoParts(source) {
+    const parts = source.repo.split("/");
+    const [owner, repo] = parts;
+    if (parts.length !== 2 ||
+        owner === undefined ||
+        repo === undefined ||
+        owner === "" ||
+        repo === "") {
+        throw new AgentError({
+            code: AGENT_ERROR_CODE.invalidInput,
+            message: `Invalid GitHub repo "${source.repo}"`,
+            data: { reason: "github-dir repo must be owner/name" },
+        });
+    }
+    return [owner, repo];
+}
+function githubContentsUrl(source, remotePath) {
+    const [owner, repo] = githubRepoParts(source);
+    const encodedPath = remotePath
+        .split("/")
+        .filter((part) => part !== "")
+        .map(encodeURIComponent)
+        .join("/");
+    const pathPart = encodedPath === "" ? "" : `/${encodedPath}`;
+    return `${GITHUB_CONTENTS_API}/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/contents${pathPart}?ref=${encodeURIComponent(source.ref)}`;
+}
+async function fetchJson(ctx, url) {
+    const response = await ctx.http.fetch(url, {
+        // biome-ignore lint/style/useNamingConvention: HTTP header names keep their wire spelling.
+        headers: { Accept: "application/vnd.github+json" },
+    });
+    if (!response.ok) {
+        throw new AgentError({
+            code: AGENT_ERROR_CODE.failed,
+            message: `GitHub skill fetch failed with status ${response.status}`,
+            data: {
+                exitCode: null,
+                stdoutTail: null,
+                stderrTail: response.statusText || null,
+            },
+        });
+    }
+    return response.json();
+}
+async function fetchBytes(ctx, url) {
+    const response = await ctx.http.fetch(url);
+    if (!response.ok) {
+        throw new AgentError({
+            code: AGENT_ERROR_CODE.failed,
+            message: `GitHub skill file fetch failed with status ${response.status}`,
+            data: {
+                exitCode: null,
+                stdoutTail: null,
+                stderrTail: response.statusText || null,
+            },
+        });
+    }
+    return Buffer.from(await response.arrayBuffer());
+}
+async function writeGithubFile(ctx, entry, targetPath) {
+    const inlineContent = readString(entry, GITHUB_CONTENTS_FIELD.content);
+    const encoding = readString(entry, GITHUB_CONTENTS_FIELD.encoding);
+    let content;
+    if (inlineContent !== null && encoding === GITHUB_CONTENT_ENCODING.base64) {
+        content = Buffer.from(inlineContent.replace(/\s/gu, ""), GITHUB_CONTENT_ENCODING.base64);
+    }
+    else {
+        const downloadUrl = readString(entry, GITHUB_CONTENTS_FIELD.downloadUrl);
+        if (downloadUrl === null) {
+            throw new AgentError({
+                code: AGENT_ERROR_CODE.failed,
+                message: "GitHub skill file is missing download_url",
+                data: { exitCode: null, stdoutTail: null, stderrTail: null },
+            });
+        }
+        content = await fetchBytes(ctx, downloadUrl);
+    }
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, content);
+}
+async function fetchGithubDirectory(ctx, source, remotePath, targetDir) {
+    const payload = await fetchJson(ctx, githubContentsUrl(source, remotePath));
+    if (!Array.isArray(payload)) {
+        throw new AgentError({
+            code: AGENT_ERROR_CODE.invalidInput,
+            message: `GitHub skill source is not a directory: ${remotePath}`,
+            data: { reason: "github-dir source must resolve to a directory" },
+        });
+    }
+    await mkdir(targetDir, { recursive: true });
+    for (const rawEntry of payload) {
+        const entry = readUnknownRecord(rawEntry);
+        if (entry === null) {
+            continue;
+        }
+        const entryType = readString(entry, GITHUB_CONTENTS_FIELD.type);
+        const entryName = readString(entry, GITHUB_CONTENTS_FIELD.name);
+        const entryPath = readString(entry, GITHUB_CONTENTS_FIELD.path);
+        if (entryName === null || entryPath === null) {
+            continue;
+        }
+        const targetPath = path.join(targetDir, entryName);
+        if (entryType === GITHUB_CONTENTS_ENTRY_TYPE.directory) {
+            await fetchGithubDirectory(ctx, source, entryPath, targetPath);
+            continue;
+        }
+        if (entryType === GITHUB_CONTENTS_ENTRY_TYPE.file) {
+            await writeGithubFile(ctx, entry, targetPath);
+        }
+    }
+}
+/** Stage the remote directory, hand it to `use`, always clean up. */
+export async function withStagedGithubDirectory(ctx, source, use) {
+    const stagingParent = await mkdtemp(path.join(os.tmpdir(), STAGING_DIRECTORY_PREFIX));
+    const stagedDir = path.join(stagingParent, githubSourceDirectoryName(source));
+    try {
+        await fetchGithubDirectory(ctx, source, source.path, stagedDir);
+        return await use(stagedDir);
+    }
+    finally {
+        await rm(stagingParent, { recursive: true, force: true });
+    }
+}

package/dist/host/mcp-list.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared `mcp list` inventory: run the agent CLI with `--json`, parse the
+ * output into `McpServerState[]`. Parsing is tolerant of the shapes the
+ * claude/codex CLIs emit (array, `{servers: [...]}`  or name-keyed maps),
+ * but non-JSON output is a typed failure, never a raw `SyntaxError`.
+ */
+import { type McpServerState } from "./capabilities.js";
+import type { HostContext } from "./context.js";
+export declare function listMcpServersViaCli(ctx: HostContext, input: {
+    command: string;
+}): Promise<McpServerState[]>;
+//# sourceMappingURL=mcp-list.d.ts.map

package/dist/host/mcp-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-list.d.ts","sourceRoot":"","sources":["../../src/host/mcp-list.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAyGhD,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GACzB,OAAO,CAAC,cAAc,EAAE,CAAC,CAsB3B"}