crewly 1.20.131 → 1.20.133

package/dist/backend/backend/src/services/skill-setup/skill-install-job.service.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Skill install jobs — `install-skill` as a background job that reports back.
+ *
+ * An agent that lacks a capability runs `install-skill --id <skill>`. This
+ * service decides whether it may (trust rule), downloads the skill from the
+ * marketplace when it is not bundled (reusing the marketplace installer),
+ * runs its setup block, and — when the job ends — sends the requesting agent
+ * a message through the normal message queue (`system_event` to its
+ * session, the path event-bus notifications use). The agent is woken by that
+ * message and carries on: tells the user it is ready, then does the task it
+ * paused.
+ *
+ * ## Trust rule
+ *
+ * - **Official** skills (see skill-discovery.service) install without asking,
+ *   including the system dependencies their setup block declares.
+ * - **Third-party** skills are refused unless the owner approved:
+ *   - the owner acting from the dashboard (`X-Crewly-Caller: dashboard`, no
+ *     agent header), or
+ *   - an agent passing `approvedByOwner`, which is **verified**: there must be
+ *     a genuine owner-authored chat message in the last
+ *     OWNER_APPROVAL_LOOKBACK_MS that approves it — the same evidence the
+ *     commitment-approval gate uses (chat-v2 `user` rows an agent cannot
+ *     write). A claim with no such message is refused. If the chat cannot be
+ *     read, the install is refused (fail closed: this runs someone else's code).
+ *
+ * @module services/skill-setup/skill-install-job.service
+ */
+import type { EnqueueMessageInput } from '../../types/messaging.types.js';
+import type { MarketplaceItem, MarketplaceOperationResult } from '../../types/marketplace.types.js';
+import { type SkillDiscoveryService } from './skill-discovery.service.js';
+import { type SetupResult, type SkillSetupRunner } from './skill-setup-runner.service.js';
+/** Job lifecycle. */
+export type InstallJobState = 'running' | 'succeeded' | 'failed';
+/** Public view of an install job. */
+export interface SkillInstallJob {
+    jobId: string;
+    skillId: string;
+    state: InstallJobState;
+    official: boolean;
+    officialReason: string;
+    estimatedMinutes: number;
+    startedAt: string;
+    finishedAt?: string;
+    /** Sessions that get the completion message */
+    requesterSessions: string[];
+    /** What the requester was doing (echoed back so it can resume) */
+    resumeNote?: string;
+    /** Tail of the job log */
+    log: string;
+    /** One-line outcome */
+    message?: string;
+    /** Setup log file */
+    logFile?: string;
+    /** Completion messages enqueued */
+    notified: boolean;
+    /** Where the skill lives once installed */
+    executePath?: string;
+}
+/** Result of asking for an install. */
+export type StartInstallResult = {
+    kind: 'job';
+    job: SkillInstallJob;
+} | {
+    kind: 'already-ready';
+    skill: {
+        id: string;
+        executePath?: string;
+        officialReason: string;
+    };
+};
+/** Input to {@link SkillInstallJobService.startInstall}. */
+export interface StartInstallInput {
+    /** Skill id (local id, directory name or registry id) */
+    skillId: string;
+    /** Agent session to notify on completion (from X-Agent-Session) */
+    requesterSession?: string;
+    /** The agent says the owner approved (verified against owner chat) */
+    approvedByOwner?: boolean;
+    /** The request comes from the owner in the dashboard */
+    ownerDashboard?: boolean;
+    /** What the agent was doing, echoed in the completion message */
+    resumeNote?: string;
+    /** Re-run setup even when a check says everything is there */
+    force?: boolean;
+    /** What the agent quotes as the owner's approval (X-Agent-Authorization), recorded in the job log */
+    ownerClaim?: string;
+}
+/** Error with a machine-readable code for the REST layer. */
+export declare class SkillInstallError extends Error {
+    readonly code: 'not_found' | 'owner_approval_required' | 'owner_approval_not_found' | 'owner_approval_unverifiable' | 'invalid_setup' | 'job_not_found';
+    readonly details: Record<string, unknown>;
+    /**
+     * @param code - `not_found`, `owner_approval_required`, `owner_approval_not_found`,
+     *   `owner_approval_unverifiable`, `invalid_setup`, `job_not_found`
+     * @param message - Human-readable message, written for the agent
+     * @param details - Extra fields for the response
+     */
+    constructor(code: 'not_found' | 'owner_approval_required' | 'owner_approval_not_found' | 'owner_approval_unverifiable' | 'invalid_setup' | 'job_not_found', message: string, details?: Record<string, unknown>);
+}
+/** Injectable dependencies. */
+export interface SkillInstallJobDeps {
+    discovery?: SkillDiscoveryService;
+    runner?: SkillSetupRunner;
+    installMarketplaceItem?: (item: MarketplaceItem) => Promise<MarketplaceOperationResult>;
+    installPathFor?: (item: MarketplaceItem) => string;
+    /** Owner-authored chat messages since a time (throws when chat is unreadable) */
+    recentOwnerMessages?: (sinceMs: number) => string[];
+    /** Enqueue a message for an agent (null queue = cannot notify) */
+    enqueue?: ((input: EnqueueMessageInput) => void) | null;
+    now?: () => number;
+    idFactory?: () => string;
+}
+/**
+ * Whether one owner message approves installing a skill.
+ *
+ * Counts a clear approval ("go ahead", "批准", "同意" — the commitment
+ * gate's tokens) or a short yes that names the skill ("ok install
+ * shady-ocr", "可以，装 shady-ocr"). A question never counts.
+ *
+ * @param message - Owner message text
+ * @param skill - Skill id and name
+ * @returns True when it approves
+ */
+export declare function isOwnerInstallApproval(message: string, skill: {
+    id: string;
+    name?: string;
+}): boolean;
+/**
+ * The message the requesting agent receives when a job ends.
+ *
+ * @param job - Finished job
+ * @param setup - Setup result (absent when the job failed before setup)
+ * @param durationMs - Job duration
+ * @returns Message text
+ */
+export declare function formatCompletionMessage(job: SkillInstallJob, setup: SetupResult | null, durationMs: number): string;
+/** Runs and tracks skill install jobs. */
+export declare class SkillInstallJobService {
+    private readonly discovery;
+    private readonly runner;
+    private readonly installMarketplaceItem;
+    private readonly installPathFor;
+    private readonly recentOwnerMessages;
+    private readonly enqueue;
+    private readonly now;
+    private readonly idFactory;
+    private readonly jobs;
+    private readonly logger;
+    /**
+     * @param deps - Injectable dependencies (all optional)
+     */
+    constructor(deps?: SkillInstallJobDeps);
+    /**
+     * Ask for a skill to be installed and set up.
+     *
+     * Returns at once: either the skill is already usable, or a job id. When
+     * a job for the same skill is running, its id is returned and the new
+     * requester is added to the completion message's recipients.
+     *
+     * @param input - Skill id, requester, approval flags
+     * @returns The job, or `already-ready`
+     * @throws SkillInstallError when the skill is unknown, untrusted, or its setup block is invalid
+     */
+    startInstall(input: StartInstallInput): Promise<StartInstallResult>;
+    /**
+     * Look up a job.
+     *
+     * @param jobId - Job id
+     * @returns The job
+     * @throws SkillInstallError `job_not_found`
+     */
+    getJob(jobId: string): SkillInstallJob;
+    /**
+     * Wait for a job to finish (tests, CLI).
+     *
+     * @param jobId - Job id
+     * @returns The finished job
+     * @throws SkillInstallError `job_not_found`
+     */
+    waitForJob(jobId: string): Promise<SkillInstallJob>;
+    /**
+     * Apply the trust rule.
+     *
+     * @param skill - Resolved skill
+     * @param input - Request
+     * @returns The owner message that approved a third-party install (undefined for official / dashboard)
+     * @throws SkillInstallError when a third-party skill lacks owner approval
+     */
+    private checkTrust;
+    /**
+     * Install (when needed), set up, then notify.
+     *
+     * @param record - Job record (mutated)
+     * @param skill - Resolved skill
+     */
+    private execute;
+    /**
+     * Read the raw `setup` block of an installed skill.
+     *
+     * @param skillDir - Skill directory
+     * @returns The block, or undefined
+     */
+    private readSetup;
+    /**
+     * Send the completion message to every requester.
+     *
+     * @param record - Finished job (mutated: notified)
+     * @param setup - Setup result
+     * @param durationMs - Duration
+     */
+    private notify;
+    /**
+     * Append to a job log, keeping the tail.
+     *
+     * @param record - Job
+     * @param text - Text
+     */
+    private append;
+    /** Forget finished jobs after the retention window. */
+    private pruneFinished;
+    /**
+     * Public view of a job.
+     *
+     * @param r - Record
+     * @returns Job
+     */
+    private toPublic;
+}
+/**
+ * One-line "I'm installing it" text the agent can relay to the user.
+ *
+ * @param job - Job
+ * @returns Message
+ */
+export declare function describeStartedJob(job: SkillInstallJob): string;
+/**
+ * The process-wide job service.
+ *
+ * @returns The service
+ */
+export declare function getSkillInstallJobService(): SkillInstallJobService;
+//# sourceMappingURL=skill-install-job.service.d.ts.map

package/dist/backend/backend/src/services/skill-setup/skill-install-job.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-install-job.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/skill-setup/skill-install-job.service.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/skill-setup/skill-install-job.service.js

@@ -0,0 +1,439 @@
+/**
+ * Skill install jobs — `install-skill` as a background job that reports back.
+ *
+ * An agent that lacks a capability runs `install-skill --id <skill>`. This
+ * service decides whether it may (trust rule), downloads the skill from the
+ * marketplace when it is not bundled (reusing the marketplace installer),
+ * runs its setup block, and — when the job ends — sends the requesting agent
+ * a message through the normal message queue (`system_event` to its
+ * session, the path event-bus notifications use). The agent is woken by that
+ * message and carries on: tells the user it is ready, then does the task it
+ * paused.
+ *
+ * ## Trust rule
+ *
+ * - **Official** skills (see skill-discovery.service) install without asking,
+ *   including the system dependencies their setup block declares.
+ * - **Third-party** skills are refused unless the owner approved:
+ *   - the owner acting from the dashboard (`X-Crewly-Caller: dashboard`, no
+ *     agent header), or
+ *   - an agent passing `approvedByOwner`, which is **verified**: there must be
+ *     a genuine owner-authored chat message in the last
+ *     OWNER_APPROVAL_LOOKBACK_MS that approves it — the same evidence the
+ *     commitment-approval gate uses (chat-v2 `user` rows an agent cannot
+ *     write). A claim with no such message is refused. If the chat cannot be
+ *     read, the install is refused (fail closed: this runs someone else's code).
+ *
+ * @module services/skill-setup/skill-install-job.service
+ */
+import { randomUUID } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { SKILL_SETUP_CONSTANTS, MESSAGE_SOURCES } from '../../constants.js';
+import { LoggerService } from '../core/logger.service.js';
+import { getInstallPath } from '../marketplace/marketplace.service.js';
+import { installItem } from '../marketplace/marketplace-installer.service.js';
+import { getMessageQueueInstance } from '../messaging/index.js';
+import { containsApprovalToken } from '../orchestrator/commitment-approval-guard.js';
+import { getChatV2Service } from '../chat-v2/chat-v2.singleton.js';
+import { validateSetupManifest } from './skill-setup-manifest.js';
+import { getSkillDiscoveryService } from './skill-discovery.service.js';
+import { getSkillSetupRunner } from './skill-setup-runner.service.js';
+/** Error with a machine-readable code for the REST layer. */
+export class SkillInstallError extends Error {
+    code;
+    details;
+    /**
+     * @param code - `not_found`, `owner_approval_required`, `owner_approval_not_found`,
+     *   `owner_approval_unverifiable`, `invalid_setup`, `job_not_found`
+     * @param message - Human-readable message, written for the agent
+     * @param details - Extra fields for the response
+     */
+    constructor(code, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'SkillInstallError';
+    }
+}
+/** Short affirmatives that approve an install when the message also names the skill. */
+const SHORT_YES = [/\byes\b/i, /\bok(ay)?\b/i, /\bsure\b/i, /\binstall\b/i, /好/, /可以/, /行/, /装/, /同意/];
+/** A question is never approval. */
+const QUESTION = /[?？]|吗\s*$|要不要|是否/;
+/**
+ * Whether one owner message approves installing a skill.
+ *
+ * Counts a clear approval ("go ahead", "批准", "同意" — the commitment
+ * gate's tokens) or a short yes that names the skill ("ok install
+ * shady-ocr", "可以，装 shady-ocr"). A question never counts.
+ *
+ * @param message - Owner message text
+ * @param skill - Skill id and name
+ * @returns True when it approves
+ */
+export function isOwnerInstallApproval(message, skill) {
+    if (!message || QUESTION.test(message))
+        return false;
+    if (containsApprovalToken(message))
+        return true;
+    const lower = message.toLowerCase();
+    const names = [skill.id, skill.name].filter((n) => !!n && n.length >= 3).map((n) => n.toLowerCase());
+    return names.some((n) => lower.includes(n)) && SHORT_YES.some((re) => re.test(message));
+}
+/**
+ * Human duration.
+ *
+ * @param ms - Milliseconds
+ * @returns e.g. "4m 10s"
+ */
+function formatDuration(ms) {
+    const s = Math.max(0, Math.round(ms / 1000));
+    return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`;
+}
+/**
+ * The message the requesting agent receives when a job ends.
+ *
+ * @param job - Finished job
+ * @param setup - Setup result (absent when the job failed before setup)
+ * @param durationMs - Job duration
+ * @returns Message text
+ */
+export function formatCompletionMessage(job, setup, durationMs) {
+    const H = SKILL_SETUP_CONSTANTS.COMPLETION_HEADERS;
+    const steps = setup?.steps.length
+        ? setup.steps.map((s) => `${s.id} ${s.status === 'satisfied' ? 'already there' : s.status}`).join(' · ')
+        : '';
+    const resume = job.resumeNote ? `\nYou paused: "${job.resumeNote}"` : '';
+    if (job.state === 'succeeded') {
+        return [
+            `${H.SUCCEEDED} ${job.skillId} is installed and ready (job ${job.jobId}, ${formatDuration(durationMs)}).`,
+            ...(steps ? [`Setup: ${steps}`] : []),
+            ...(job.executePath ? [`Run it: bash ${job.executePath} (see SKILL.md next to it)`] : []),
+        ].join('\n') + `${resume}\nNext: tell the user in one line that it is ready, then do the task you paused — now, without waiting to be asked.`;
+    }
+    return [
+        `${H.FAILED} ${job.skillId} (job ${job.jobId}, ${formatDuration(durationMs)}): ${job.message ?? 'unknown error'}`,
+        ...(steps ? [`Setup: ${steps}`] : []),
+        ...(job.logFile ? [`Log: ${job.logFile}`] : []),
+    ].join('\n') + `${resume}\nNext: tell the user plainly what is missing and the fix quoted above (e.g. the command the owner can run). Do not retry the same install until something has changed.`;
+}
+/** Runs and tracks skill install jobs. */
+export class SkillInstallJobService {
+    discovery;
+    runner;
+    installMarketplaceItem;
+    installPathFor;
+    recentOwnerMessages;
+    enqueue;
+    now;
+    idFactory;
+    jobs = new Map();
+    logger = LoggerService.getInstance().createComponentLogger('SkillInstallJobs');
+    /**
+     * @param deps - Injectable dependencies (all optional)
+     */
+    constructor(deps = {}) {
+        this.discovery = deps.discovery ?? getSkillDiscoveryService();
+        this.runner = deps.runner ?? getSkillSetupRunner();
+        this.installMarketplaceItem = deps.installMarketplaceItem ?? installItem;
+        this.installPathFor = deps.installPathFor ?? ((item) => getInstallPath(item.type, item.id));
+        this.recentOwnerMessages = deps.recentOwnerMessages ?? ((since) => getChatV2Service().getRecentOwnerMessageContents(since));
+        // Resolved per job: the queue is created after this service at startup.
+        this.enqueue =
+            deps.enqueue !== undefined
+                ? () => deps.enqueue ?? null
+                : () => {
+                    const queue = getMessageQueueInstance();
+                    return queue ? (input) => void queue.enqueue(input) : null;
+                };
+        this.now = deps.now ?? Date.now;
+        this.idFactory = deps.idFactory ?? (() => randomUUID().slice(0, 8));
+    }
+    /**
+     * Ask for a skill to be installed and set up.
+     *
+     * Returns at once: either the skill is already usable, or a job id. When
+     * a job for the same skill is running, its id is returned and the new
+     * requester is added to the completion message's recipients.
+     *
+     * @param input - Skill id, requester, approval flags
+     * @returns The job, or `already-ready`
+     * @throws SkillInstallError when the skill is unknown, untrusted, or its setup block is invalid
+     */
+    async startInstall(input) {
+        const skill = await this.discovery.resolve(input.skillId);
+        if (!skill) {
+            throw new SkillInstallError('not_found', `No skill "${input.skillId}" is bundled with Crewly or listed in the marketplace. Run find-skill --query "<what you need>" to search.`);
+        }
+        // A job already running for this skill passed the trust check: join it.
+        this.pruneFinished();
+        const running = [...this.jobs.values()].find((j) => j.skillId === skill.id && j.state === 'running');
+        if (running) {
+            if (input.requesterSession && !running.requesterSessions.includes(input.requesterSession)) {
+                running.requesterSessions.push(input.requesterSession);
+            }
+            return { kind: 'job', job: this.toPublic(running) };
+        }
+        // Nothing to install: say so instead of making the agent wait for a message.
+        if (!input.force && skill.installed && !skill.manifestError) {
+            await this.discovery.probe(skill);
+            if (skill.ready) {
+                return { kind: 'already-ready', skill: { id: skill.id, executePath: skill.executePath, officialReason: skill.officialReason } };
+            }
+        }
+        const evidence = this.checkTrust(skill, input);
+        if (skill.manifestError) {
+            throw new SkillInstallError('invalid_setup', `The setup block of ${skill.id} is invalid, so it was not run: ${skill.manifestError}`);
+        }
+        const record = {
+            jobId: this.idFactory(),
+            skillId: skill.id,
+            state: 'running',
+            official: skill.official,
+            officialReason: skill.officialReason,
+            estimatedMinutes: skill.setup.estimatedMinutes ?? SKILL_SETUP_CONSTANTS.DEFAULT_ESTIMATED_MINUTES,
+            startedAt: new Date(this.now()).toISOString(),
+            requesterSessions: input.requesterSession ? [input.requesterSession] : [],
+            ...(input.resumeNote ? { resumeNote: input.resumeNote } : {}),
+            log: evidence
+                ? `Third-party skill approved by the owner in chat: "${evidence.slice(0, 300)}"` +
+                    (input.ownerClaim ? `\nThe agent cited: "${input.ownerClaim.slice(0, 300)}"` : '') + '\n'
+                : input.ownerDashboard && !skill.official
+                    ? 'Third-party skill installed by the owner from the dashboard.\n'
+                    : '',
+            notified: false,
+            executePath: skill.executePath,
+            finishedAtMs: null,
+            done: null,
+        };
+        this.jobs.set(record.jobId, record);
+        this.logger.info('Skill install started', { jobId: record.jobId, skillId: skill.id, official: skill.official, requesters: record.requesterSessions });
+        record.done = this.execute(record, skill);
+        return { kind: 'job', job: this.toPublic(record) };
+    }
+    /**
+     * Look up a job.
+     *
+     * @param jobId - Job id
+     * @returns The job
+     * @throws SkillInstallError `job_not_found`
+     */
+    getJob(jobId) {
+        const record = this.jobs.get(jobId);
+        if (!record)
+            throw new SkillInstallError('job_not_found', `Install job not found: ${jobId}`);
+        return this.toPublic(record);
+    }
+    /**
+     * Wait for a job to finish (tests, CLI).
+     *
+     * @param jobId - Job id
+     * @returns The finished job
+     * @throws SkillInstallError `job_not_found`
+     */
+    async waitForJob(jobId) {
+        const record = this.jobs.get(jobId);
+        if (!record)
+            throw new SkillInstallError('job_not_found', `Install job not found: ${jobId}`);
+        if (record.done)
+            await record.done;
+        return this.toPublic(record);
+    }
+    /**
+     * Apply the trust rule.
+     *
+     * @param skill - Resolved skill
+     * @param input - Request
+     * @returns The owner message that approved a third-party install (undefined for official / dashboard)
+     * @throws SkillInstallError when a third-party skill lacks owner approval
+     */
+    checkTrust(skill, input) {
+        if (skill.official || input.ownerDashboard)
+            return undefined;
+        const who = `"${skill.id}" is a third-party skill (${skill.officialReason})`;
+        if (!input.approvedByOwner) {
+            throw new SkillInstallError('owner_approval_required', `${who}, so it is not installed automatically. Ask the owner in chat whether to install it (say what it is and who publishes it). ` +
+                `Only after they say yes, run: install-skill --id ${skill.id} --approved-by-owner`, { official: false, officialReason: skill.officialReason });
+        }
+        let messages;
+        try {
+            messages = this.recentOwnerMessages(this.now() - SKILL_SETUP_CONSTANTS.OWNER_APPROVAL_LOOKBACK_MS);
+        }
+        catch (error) {
+            throw new SkillInstallError('owner_approval_unverifiable', `${who}. --approved-by-owner could not be checked because the owner's chat history is unreadable (${error instanceof Error ? error.message : String(error)}); not installing.`);
+        }
+        const evidence = messages.find((m) => isOwnerInstallApproval(m, { id: skill.id, name: skill.name }));
+        if (!evidence) {
+            const hours = Math.round(SKILL_SETUP_CONSTANTS.OWNER_APPROVAL_LOOKBACK_MS / 3_600_000);
+            throw new SkillInstallError('owner_approval_not_found', `${who}. --approved-by-owner was passed, but no owner message in the last ${hours}h approves installing it. ` +
+                `Ask the owner in chat first (name the skill); run this again after they say yes.`);
+        }
+        this.logger.info('Third-party skill install approved by owner message', { skillId: skill.id, evidence: evidence.slice(0, 200), claim: input.ownerClaim });
+        return evidence;
+    }
+    /**
+     * Install (when needed), set up, then notify.
+     *
+     * @param record - Job record (mutated)
+     * @param skill - Resolved skill
+     */
+    async execute(record, skill) {
+        const started = this.now();
+        let setup = null;
+        try {
+            let skillDir = skill.skillDir;
+            let manifest = skill.manifest;
+            if (!skill.installed || !skillDir) {
+                const item = skill.registryItem;
+                if (!item)
+                    throw new Error('not installed and not in the registry');
+                this.append(record, `Downloading ${item.name} v${item.version} from the marketplace…\n`);
+                let installed = item;
+                let res = await this.installMarketplaceItem(item);
+                if (!res.success && item.fallback) {
+                    // Premium archives can be missing from the CDN; the public copy of the same skill installs.
+                    this.append(record, `${res.message}; trying the public registry copy…\n`);
+                    installed = item.fallback;
+                    res = await this.installMarketplaceItem(item.fallback);
+                }
+                if (!res.success)
+                    throw new Error(`marketplace install failed: ${res.message}`);
+                this.append(record, `${res.message}\n`);
+                skillDir = this.installPathFor(installed);
+                record.executePath = path.join(skillDir, 'execute.sh');
+                // The downloaded skill.json is authoritative for setup.
+                const local = this.readSetup(skillDir);
+                if (local !== undefined) {
+                    const v = validateSetupManifest(local);
+                    if (!v.valid)
+                        throw new Error(`the installed skill's setup block is invalid: ${v.errors.join('; ')}`);
+                    manifest = v.manifest;
+                }
+            }
+            if (manifest) {
+                setup = await this.runner.runSetup({
+                    skillId: skill.id,
+                    skillDir,
+                    manifest,
+                    onProgress: (e) => this.append(record, `[${e.stepId}] ${e.phase}: ${e.message}\n`),
+                });
+                record.logFile = setup.logFile;
+                if (!setup.success)
+                    throw new Error(setup.error ?? 'setup failed');
+            }
+            else {
+                this.append(record, 'No setup needed.\n');
+            }
+            record.state = 'succeeded';
+            record.message = `${skill.id} is installed and ready`;
+        }
+        catch (error) {
+            record.state = 'failed';
+            record.message = error instanceof Error ? error.message : String(error);
+            this.append(record, `FAILED: ${record.message}\n`);
+        }
+        record.finishedAtMs = this.now();
+        record.finishedAt = new Date(record.finishedAtMs).toISOString();
+        this.logger.info('Skill install finished', { jobId: record.jobId, skillId: record.skillId, state: record.state, message: record.message });
+        this.notify(record, setup, record.finishedAtMs - started);
+    }
+    /**
+     * Read the raw `setup` block of an installed skill.
+     *
+     * @param skillDir - Skill directory
+     * @returns The block, or undefined
+     */
+    readSetup(skillDir) {
+        try {
+            return JSON.parse(fs.readFileSync(path.join(skillDir, 'skill.json'), 'utf-8')).setup;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Send the completion message to every requester.
+     *
+     * @param record - Finished job (mutated: notified)
+     * @param setup - Setup result
+     * @param durationMs - Duration
+     */
+    notify(record, setup, durationMs) {
+        if (record.requesterSessions.length === 0)
+            return;
+        const enqueue = this.enqueue();
+        if (!enqueue) {
+            this.logger.warn('Message queue unavailable; install result not delivered', { jobId: record.jobId });
+            return;
+        }
+        const content = formatCompletionMessage(this.toPublic(record), setup, durationMs);
+        for (const session of record.requesterSessions) {
+            try {
+                enqueue({
+                    content,
+                    conversationId: SKILL_SETUP_CONSTANTS.COMPLETION_CONVERSATION_ID,
+                    source: MESSAGE_SOURCES.SYSTEM_EVENT,
+                    targetSession: session,
+                });
+                record.notified = true;
+            }
+            catch (error) {
+                this.logger.warn('Failed to enqueue install result', { jobId: record.jobId, session, error: error instanceof Error ? error.message : String(error) });
+            }
+        }
+    }
+    /**
+     * Append to a job log, keeping the tail.
+     *
+     * @param record - Job
+     * @param text - Text
+     */
+    append(record, text) {
+        const next = record.log + text;
+        const max = SKILL_SETUP_CONSTANTS.JOB_LOG_MAX_CHARS;
+        record.log = next.length > max ? next.slice(next.length - max) : next;
+    }
+    /** Forget finished jobs after the retention window. */
+    pruneFinished() {
+        const cutoff = this.now() - SKILL_SETUP_CONSTANTS.JOB_RETENTION_MS;
+        for (const [id, job] of this.jobs) {
+            if (job.finishedAtMs !== null && job.finishedAtMs < cutoff)
+                this.jobs.delete(id);
+        }
+    }
+    /**
+     * Public view of a job.
+     *
+     * @param r - Record
+     * @returns Job
+     */
+    toPublic(r) {
+        const view = { ...r, requesterSessions: [...r.requesterSessions] };
+        delete view.finishedAtMs;
+        delete view.done;
+        return view;
+    }
+}
+/**
+ * One-line "I'm installing it" text the agent can relay to the user.
+ *
+ * @param job - Job
+ * @returns Message
+ */
+export function describeStartedJob(job) {
+    return (`Installing ${job.skillId} in the background (about ${job.estimatedMinutes} min). ` +
+        `Tell the user now, in one line, that you are installing it and roughly how long it takes; ` +
+        `you will get a ${SKILL_SETUP_CONSTANTS.COMPLETION_HEADERS.SUCCEEDED} or ${SKILL_SETUP_CONSTANTS.COMPLETION_HEADERS.FAILED} message when it ends — continue then.`);
+}
+let jobServiceSingleton = null;
+/**
+ * The process-wide job service.
+ *
+ * @returns The service
+ */
+export function getSkillInstallJobService() {
+    if (!jobServiceSingleton)
+        jobServiceSingleton = new SkillInstallJobService();
+    return jobServiceSingleton;
+}
+//# sourceMappingURL=skill-install-job.service.js.map