qlogicagent 2.13.3 → 2.13.5

package/dist/cli/core-tools/team-tool-service.js

@@ -0,0 +1,326 @@
+import * as path from "node:path";
+import { AgentProcessManager } from "../../runtime/infra/agent-process.js";
+import { getDefaultPathService } from "../../runtime/infra/default-path-service.js";
+import { generateTaskId } from "../../runtime/infra/task-runtime.js";
+import { createAgentWorktree, findGitRoot, removeAgentWorktree } from "../../runtime/infra/worktree-backend.js";
+import { buildSubagentSystemPrompt, personaForTeamMember } from "./fork-system-prompt.js";
+/**
+ * Guardrails on team size. Members are real subprocesses in git worktrees, so an
+ * unbounded `members` array is a fork bomb. Cap per-team and total-concurrent.
+ */
+const MAX_TEAM_MEMBERS = 8;
+const MAX_CONCURRENT_MEMBERS = 16;
+/** Extract the reply text from an AgentProcessManager.sendTask result. */
+function extractReplyText(result) {
+    if (result && typeof result === "object" && "content" in result) {
+        const content = result.content;
+        if (typeof content === "string")
+            return content;
+    }
+    return "";
+}
+/** Format an inbound teammate message so the receiving member knows the sender. */
+function formatInbound(message, fromId) {
+    return `[message from ${fromId}]\n${message}`;
+}
+/** One-line live status for a member, shown by `task output`. */
+function formatMemberStatus(status) {
+    if (!status)
+        return "(member process not found — already exited?)";
+    const parts = [`state=${status.state}`, status.alive ? "alive" : "dead"];
+    if (status.lastToolCall)
+        parts.push(`lastTool=${status.lastToolCall}`);
+    if (status.idleFor != null)
+        parts.push(`idle=${status.idleFor}s`);
+    if (status.runningFor != null)
+        parts.push(`running=${Math.round(status.runningFor / 1000)}s`);
+    if (status.mediaProgress)
+        parts.push(`media=${status.mediaProgress.percent}%`);
+    if (status.error)
+        parts.push(`error=${status.error}`);
+    return parts.join(" · ");
+}
+export function createTeamToolService(host, log, registry) {
+    const activeTeams = new Map();
+    // memberId → unified-panel taskId, so onExit/deleteTeam can settle the task.
+    const memberTaskIds = new Map();
+    const worktreeLog = { info: (message) => log.info(message), warn: (message) => log.warn(message) };
+    const agentProcessManager = new AgentProcessManager({
+        onNotification: (memberId, method, params) => {
+            host.sendNotification("team.member.notification", { memberId, method, params });
+        },
+        onStateChange: (memberId, state) => {
+            host.sendNotification("team.member.state", { memberId, state });
+            const handle = agentProcessManager.getHandle(memberId);
+            const tracker = agentProcessManager.getUsageTracker(memberId);
+            const usage = tracker?.getUsage();
+            host.emitAgentStatus(memberId, state, {
+                missedBeats: agentProcessManager.getMissedBeats(memberId),
+                lastActivityAt: handle?.lastActivityAt,
+                usage: usage && usage.totalTokens > 0
+                    ? { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens, totalTokens: usage.totalTokens }
+                    : undefined,
+            });
+        },
+        onExit: (memberId, code, signal) => {
+            for (const team of activeTeams.values()) {
+                const member = team.members.find(m => m.cwd && teamMemberId(team.name, m.name) === memberId);
+                if (member)
+                    member.isActive = false;
+            }
+            registry.unregister(memberId);
+            // Settle the unified-panel task. Idempotent vs. a concurrent deleteTeam
+            // (which marks it cancelled and clears the id first).
+            const taskId = memberTaskIds.get(memberId);
+            if (taskId) {
+                host.getBackgroundTasks()?.settleExternalTask(taskId, code === 0 ? "completed" : "failed", `exited (code=${code}, signal=${signal})`);
+                memberTaskIds.delete(memberId);
+            }
+            log.info(`[team] member ${memberId} exited (code=${code}, signal=${signal})`);
+        },
+        onMcpToolCall: (memberId, tool, args) => host.handleMcpToolCall(memberId, tool, args),
+        log: { info: (message) => log.info(message), warn: (message) => log.warn(message), debug: (message) => log.debug(message) },
+        sessionDir: path.join(getDefaultPathService().getUserAgentHome(), "agent-logs"),
+    });
+    return {
+        async createTeam(params) {
+            if (activeTeams.has(params.teamName)) {
+                return { success: false, error: `Team "${params.teamName}" already exists.` };
+            }
+            // Guardrail: members are real subprocesses — cap per-team and total live.
+            const requested = params.members?.length ?? 0;
+            if (requested > MAX_TEAM_MEMBERS) {
+                return {
+                    success: false,
+                    error: `Team size ${requested} exceeds the per-team limit of ${MAX_TEAM_MEMBERS}. ` +
+                        `Split the work into phases or reuse members via team(action="send").`,
+                };
+            }
+            const liveMembers = [...activeTeams.values()]
+                .reduce((n, t) => n + t.members.filter(m => m.isActive).length, 0);
+            if (liveMembers + requested > MAX_CONCURRENT_MEMBERS) {
+                return {
+                    success: false,
+                    error: `Creating ${requested} member(s) would exceed the concurrent limit of ` +
+                        `${MAX_CONCURRENT_MEMBERS} (currently ${liveMembers} live). Disband an idle team first.`,
+                };
+            }
+            const gitRoot = await findGitRoot();
+            const members = [];
+            for (const memberParams of params.members ?? []) {
+                const member = { ...memberParams, isActive: true };
+                if (gitRoot) {
+                    const slug = `team-${params.teamName}-${memberParams.name}`.replace(/[^a-zA-Z0-9-]/g, "-").toLowerCase();
+                    const worktree = await createAgentWorktree(gitRoot, slug, worktreeLog);
+                    if (worktree) {
+                        member.worktreePath = worktree.worktreePath;
+                        member.worktreeBranch = worktree.branch;
+                        member.cwd = worktree.worktreePath;
+                        log.info(`[team] provisioned worktree for ${memberParams.name}: ${worktree.worktreePath}`);
+                    }
+                    else {
+                        member.cwd = process.cwd();
+                        log.warn(`[team] worktree provision failed for ${memberParams.name}, using shared cwd`);
+                    }
+                }
+                else {
+                    member.cwd = process.cwd();
+                }
+                members.push(member);
+            }
+            const team = {
+                name: params.teamName,
+                description: params.description,
+                leadId: host.currentSessionId ?? "default",
+                members,
+                createdAt: new Date().toISOString(),
+            };
+            activeTeams.set(params.teamName, team);
+            const spawnFailures = [];
+            for (const member of members) {
+                if (!member.cwd)
+                    continue;
+                const memberId = teamMemberId(params.teamName, member.name);
+                try {
+                    const llm = host.getLlmConfig();
+                    // Inject the member's standing context (persona + parent memory) —
+                    // symmetric with the in-process fork. Rules come from the member's
+                    // own worktree pipeline (includeRules:false avoids duplicating them).
+                    const memberSystemPrompt = await buildSubagentSystemPrompt({
+                        persona: personaForTeamMember(member.name, member.role),
+                        memoryIndex: host.getMemoryIndex(),
+                        includeRules: false,
+                    });
+                    await agentProcessManager.spawn({
+                        memberId,
+                        name: member.name,
+                        cwd: member.cwd,
+                        prompt: `You are the "${member.name}" team member. Role: ${member.role}.`,
+                        agentType: member.role,
+                        verbose: host.verbose,
+                        ...(memberSystemPrompt ? { systemPrompt: memberSystemPrompt } : {}),
+                        // Leader's resolved provider → member's standing session config.
+                        // A standalone member cannot self-provision a provider for its
+                        // reply turns (team send) without this.
+                        ...(llm ? { provider: llm.provider, model: llm.model, apiKey: llm.apiKey, baseUrl: llm.baseUrl } : {}),
+                    });
+                    // Register the member so team(action="send") can route to it.
+                    registry.register({
+                        memberId,
+                        name: member.name,
+                        teamName: params.teamName,
+                        role: member.role,
+                        deliver: async (message, fromId) => extractReplyText(await agentProcessManager.sendTask(memberId, formatInbound(message, fromId))),
+                        isAlive: () => agentProcessManager.isAlive(memberId),
+                    });
+                    // Surface the member in the unified task panel (list/output/cancel).
+                    const tasks = host.getBackgroundTasks();
+                    if (tasks) {
+                        const memberTask = {
+                            taskId: generateTaskId("team_member"),
+                            type: "team_member",
+                            label: `${member.name} (${member.role})`,
+                            permissionRole: "worker",
+                            isolation: member.worktreePath ? "worktree" : "shared",
+                            lifecycle: "running",
+                            depth: 1,
+                            maxTurns: 0,
+                            tokenBudget: 0,
+                            startedAt: Date.now(),
+                            teamName: params.teamName,
+                            agentName: member.name,
+                            memberId,
+                            pid: agentProcessManager.getHandle(memberId)?.pid,
+                            worktreePath: member.worktreePath,
+                            worktreeBranch: member.worktreeBranch,
+                        };
+                        tasks.registerExternalTask(memberTask, {
+                            cancel: () => {
+                                agentProcessManager.kill(memberId);
+                                agentProcessManager.remove(memberId);
+                                registry.unregister(memberId);
+                                member.isActive = false;
+                            },
+                            readStatus: () => formatMemberStatus(agentProcessManager.getStatus(memberId)),
+                        });
+                        memberTaskIds.set(memberId, memberTask.taskId);
+                    }
+                    log.info(`[team] spawned child process for ${member.name} in ${member.cwd}`);
+                }
+                catch (err) {
+                    const errMsg = err instanceof Error ? err.message : String(err);
+                    log.warn(`[team] failed to spawn child process for ${member.name}: ${errMsg}`);
+                    member.isActive = false;
+                    spawnFailures.push({ name: member.name, error: errMsg });
+                }
+            }
+            // Fail-loud: every member failed to spawn → team creation failed.
+            const spawnable = members.filter(m => m.cwd).length;
+            if (spawnable > 0 && spawnFailures.length === spawnable) {
+                activeTeams.delete(params.teamName);
+                return {
+                    success: false,
+                    error: `All ${spawnable} team member(s) failed to spawn: ` +
+                        spawnFailures.map(f => `${f.name} (${f.error})`).join("; "),
+                };
+            }
+            host.sendNotification("team.updated", {
+                teamName: params.teamName,
+                action: "created",
+                members: team.members.map(member => ({
+                    agentName: member.name,
+                    role: member.role,
+                    worktreePath: member.worktreePath,
+                    pid: agentProcessManager.getHandle(teamMemberId(params.teamName, member.name))?.pid,
+                })),
+            });
+            // Partial failure is surfaced in the result so the caller doesn't think
+            // a half-dead team is fully operational.
+            return spawnFailures.length > 0
+                ? { success: true, team, partialFailures: spawnFailures }
+                : { success: true, team };
+        },
+        async deleteTeam(teamName) {
+            const team = activeTeams.get(teamName);
+            if (!team) {
+                return { success: false, error: `Team "${teamName}" not found.` };
+            }
+            for (const member of team.members) {
+                const memberId = teamMemberId(teamName, member.name);
+                registry.unregister(memberId);
+                agentProcessManager.kill(memberId);
+                agentProcessManager.remove(memberId);
+                // Mark the panel task cancelled before the kill's onExit fires (that
+                // late settle is dropped as terminal-already). Clear the id first.
+                const taskId = memberTaskIds.get(memberId);
+                if (taskId) {
+                    memberTaskIds.delete(memberId);
+                    host.getBackgroundTasks()?.settleExternalTask(taskId, "cancelled", "team disbanded");
+                }
+            }
+            const gitRoot = await findGitRoot();
+            if (gitRoot) {
+                for (const member of team.members) {
+                    if (member.worktreePath && member.worktreeBranch) {
+                        await removeAgentWorktree(gitRoot, member.worktreePath, member.worktreeBranch, worktreeLog);
+                        log.info(`[team] cleaned up worktree for ${member.name}: ${member.worktreePath}`);
+                    }
+                }
+            }
+            activeTeams.delete(teamName);
+            host.sendNotification("team.updated", {
+                teamName,
+                action: "destroyed",
+                members: [],
+            });
+            return { success: true };
+        },
+        async listTeams() {
+            return { success: true, teams: [...activeTeams.values()] };
+        },
+        async getTeamStatus(teamName) {
+            const team = activeTeams.get(teamName);
+            if (!team)
+                return { success: false, error: `Team "${teamName}" not found.` };
+            const memberProgress = {};
+            for (const member of team.members) {
+                const memberId = teamMemberId(teamName, member.name);
+                const status = agentProcessManager.getStatus(memberId);
+                if (status) {
+                    member.isActive = status.alive;
+                    memberProgress[member.name] = {
+                        mediaProgress: status.mediaProgress,
+                        lastToolCall: status.lastToolCall,
+                        idleFor: status.idleFor,
+                        runningFor: status.runningFor,
+                    };
+                }
+            }
+            return { success: true, team, memberProgress };
+        },
+        async sendMessage(params) {
+            log.info(`[team send] ${params.senderId} -> ${params.to}: ${params.message}`);
+            const outcome = await registry.deliver(params.to, params.message, params.senderId);
+            if (!outcome.ok) {
+                return { success: false, error: outcome.error };
+            }
+            return {
+                success: true,
+                recipients: outcome.replies?.map((r) => r.name) ?? [],
+                replies: outcome.replies,
+            };
+        },
+        getSenderId() {
+            return host.currentSessionId ?? "default";
+        },
+        listTeammates() {
+            return registry.list().filter((e) => e.alive).map((e) => e.name);
+        },
+        dispose() {
+            agentProcessManager.dispose();
+        },
+    };
+}
+function teamMemberId(teamName, memberName) {
+    return `team-${teamName}-${memberName}`.replace(/[^a-zA-Z0-9-]/g, "-").toLowerCase();
+}

package/dist/cli/core-tools/team-tool-service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/core-tools/team-tool-service.test.js

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { createTeamToolService } from "./team-tool-service.js";
+import { TeamRegistry } from "./team-registry.js";
+/** Noop logger — the overloaded signatures all accept a no-arg fn structurally. */
+const noopLog = {
+    info: () => { }, warn: () => { }, error: () => { }, debug: () => { },
+};
+function makeHost() {
+    return {
+        currentSessionId: "sess-test",
+        verbose: false,
+        getLlmConfig: () => null,
+        getMemoryIndex: () => null,
+        getBackgroundTasks: () => null,
+        sendNotification: () => { },
+        emitAgentStatus: () => { },
+        handleMcpToolCall: async () => ({}),
+    };
+}
+describe("team-tool-service — size guardrails", () => {
+    it("rejects a team over the per-team member cap before any spawn", async () => {
+        const svc = createTeamToolService(makeHost(), noopLog, new TeamRegistry());
+        try {
+            const members = Array.from({ length: 9 }, (_, i) => ({ name: `m${i}`, role: "worker" }));
+            const res = await svc.createTeam({ teamName: "too-big", members });
+            expect(res.success).toBe(false);
+            // The error names the limit so the model knows how to recover.
+            expect(res.error).toContain("per-team limit of 8");
+        }
+        finally {
+            svc.dispose();
+        }
+    });
+    it("rejects a duplicate team name", async () => {
+        const svc = createTeamToolService(makeHost(), noopLog, new TeamRegistry());
+        try {
+            // Zero members → passes the cap, no subprocess spawned, lands as an empty team.
+            const first = await svc.createTeam({ teamName: "dup", members: [] });
+            expect(first.success).toBe(true);
+            const second = await svc.createTeam({ teamName: "dup", members: [] });
+            expect(second.success).toBe(false);
+            expect(second.error).toContain("already exists");
+        }
+        finally {
+            svc.dispose();
+        }
+    });
+});

package/dist/cli/credential-vault.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Credential Vault (spec D29, IT-7) — owner-scoped, encrypted-at-rest storage for workflow
+ * node credentials (http auth headers, oauth tokens, …).
+ *
+ * Storage layout (under the active owner profile, sibling of settings):
+ *   <ownerProfile>/credentials/.vault-key      random 32-byte key, created once (0600)
+ *   <ownerProfile>/credentials/<id>.json       AES-256-GCM ciphertext envelope
+ *
+ * Threat model: the key and the data live in separate files on the SAME machine — this protects
+ * against credential files leaking individually (backups, copy-paste, bundle export), not against
+ * an attacker with full user-account access (no user master password exists to anchor more).
+ *
+ * Hard rules (D29): decrypted secrets exist only inside the engine process at execution time —
+ * list() never returns secret material, and nothing here is ever serialized into defs, bundles,
+ * exports, or Hub publishes (the bundle sanitizer strips by key shape as the second fence).
+ */
+export type CredentialType = "apiKey" | "bearer" | "basic" | "oauth2" | "custom";
+/** Public, secret-free view (what credential.list returns / the UI renders). */
+export interface CredentialSummary {
+    id: string;
+    type: CredentialType;
+    label: string;
+    createdAt: string;
+    updatedAt: string;
+    /** Secret-free hints for pickers (e.g. apiKey header name, oauth2 scopes). */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Secret payload shapes by type (validated on create):
+ *   apiKey: { headerName, value } · bearer: { token } · basic: { username, password }
+ *   oauth2: { accessToken, refreshToken?, tokenUrl?, clientId?, clientSecret?, scopes? }
+ *   custom: { headers: Record<string,string> }
+ */
+export type CredentialData = Record<string, unknown>;
+export declare class CredentialVault {
+    private readonly dir;
+    constructor(ownerProfileDir?: string);
+    private keyPath;
+    private ensureKey;
+    private encrypt;
+    private decrypt;
+    private filePath;
+    list(): CredentialSummary[];
+    create(input: {
+        type: CredentialType;
+        label: string;
+        data: CredentialData;
+        meta?: Record<string, unknown>;
+        id?: string;
+    }): CredentialSummary;
+    /** Decrypted payload — engine-internal use ONLY (execution-time injection). Never over RPC. */
+    get(id: string): {
+        summary: CredentialSummary;
+        data: CredentialData;
+    };
+    delete(id: string): boolean;
+    /** Update the secret payload in place (e.g. oauth2 token refresh / exchange completion). */
+    updateData(id: string, data: CredentialData, metaPatch?: Record<string, unknown>): CredentialSummary;
+}
+export declare function validateCredentialData(type: CredentialType, data: CredentialData): void;
+/** Materialize a credential into HTTP request headers (the engine-side injection point). */
+export declare function credentialToHeaders(type: CredentialType, data: CredentialData): Record<string, string>;

package/dist/cli/credential-vault.js

@@ -0,0 +1,190 @@
+/**
+ * Credential Vault (spec D29, IT-7) — owner-scoped, encrypted-at-rest storage for workflow
+ * node credentials (http auth headers, oauth tokens, …).
+ *
+ * Storage layout (under the active owner profile, sibling of settings):
+ *   <ownerProfile>/credentials/.vault-key      random 32-byte key, created once (0600)
+ *   <ownerProfile>/credentials/<id>.json       AES-256-GCM ciphertext envelope
+ *
+ * Threat model: the key and the data live in separate files on the SAME machine — this protects
+ * against credential files leaking individually (backups, copy-paste, bundle export), not against
+ * an attacker with full user-account access (no user master password exists to anchor more).
+ *
+ * Hard rules (D29): decrypted secrets exist only inside the engine process at execution time —
+ * list() never returns secret material, and nothing here is ever serialized into defs, bundles,
+ * exports, or Hub publishes (the bundle sanitizer strips by key shape as the second fence).
+ */
+import { createCipheriv, createDecipheriv, randomBytes, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { getOwnerProfileDir } from "../runtime/infra/agent-paths.js";
+const ALGO = "aes-256-gcm";
+export class CredentialVault {
+    dir;
+    constructor(ownerProfileDir = getOwnerProfileDir()) {
+        this.dir = join(ownerProfileDir, "credentials");
+    }
+    keyPath() {
+        return join(this.dir, ".vault-key");
+    }
+    ensureKey() {
+        if (!existsSync(this.dir))
+            mkdirSync(this.dir, { recursive: true });
+        const p = this.keyPath();
+        if (!existsSync(p)) {
+            const key = randomBytes(32);
+            writeFileSync(p, key.toString("base64"), { mode: 0o600 });
+            return key;
+        }
+        return Buffer.from(readFileSync(p, "utf-8").trim(), "base64");
+    }
+    encrypt(data) {
+        const key = this.ensureKey();
+        const iv = randomBytes(12);
+        const cipher = createCipheriv(ALGO, key, iv);
+        const ct = Buffer.concat([cipher.update(JSON.stringify(data), "utf-8"), cipher.final()]);
+        return `${iv.toString("base64")}.${cipher.getAuthTag().toString("base64")}.${ct.toString("base64")}`;
+    }
+    decrypt(enc) {
+        const key = this.ensureKey();
+        const [ivB64, tagB64, ctB64] = enc.split(".");
+        if (!ivB64 || !tagB64 || !ctB64)
+            throw new Error("credential vault: malformed ciphertext envelope");
+        const decipher = createDecipheriv(ALGO, key, Buffer.from(ivB64, "base64"));
+        decipher.setAuthTag(Buffer.from(tagB64, "base64"));
+        const pt = Buffer.concat([decipher.update(Buffer.from(ctB64, "base64")), decipher.final()]);
+        return JSON.parse(pt.toString("utf-8"));
+    }
+    filePath(id) {
+        if (!/^[\w-]+$/.test(id))
+            throw new Error(`credential vault: illegal id "${id}"`);
+        return join(this.dir, `${id}.json`);
+    }
+    list() {
+        if (!existsSync(this.dir))
+            return [];
+        const out = [];
+        for (const f of readdirSync(this.dir)) {
+            if (!f.endsWith(".json"))
+                continue;
+            try {
+                const env = JSON.parse(readFileSync(join(this.dir, f), "utf-8"));
+                out.push({ id: env.id, type: env.type, label: env.label, createdAt: env.createdAt, updatedAt: env.updatedAt, meta: env.meta });
+            }
+            catch {
+                // A corrupt envelope is surfaced as absent from list(); get() on it throws loud.
+            }
+        }
+        return out.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    }
+    create(input) {
+        validateCredentialData(input.type, input.data);
+        const id = input.id ?? `cred_${randomUUID().slice(0, 8)}`;
+        const now = new Date().toISOString();
+        const envelope = {
+            id,
+            type: input.type,
+            label: input.label || id,
+            createdAt: now,
+            updatedAt: now,
+            ...(input.meta ? { meta: input.meta } : {}),
+            enc: this.encrypt(input.data),
+        };
+        if (!existsSync(this.dir))
+            mkdirSync(this.dir, { recursive: true });
+        writeFileSync(this.filePath(id), JSON.stringify(envelope, null, 2), { mode: 0o600 });
+        return { id, type: envelope.type, label: envelope.label, createdAt: now, updatedAt: now, meta: envelope.meta };
+    }
+    /** Decrypted payload — engine-internal use ONLY (execution-time injection). Never over RPC. */
+    get(id) {
+        const p = this.filePath(id);
+        if (!existsSync(p))
+            throw new Error(`credential "${id}" not found`);
+        const env = JSON.parse(readFileSync(p, "utf-8"));
+        return {
+            summary: { id: env.id, type: env.type, label: env.label, createdAt: env.createdAt, updatedAt: env.updatedAt, meta: env.meta },
+            data: this.decrypt(env.enc),
+        };
+    }
+    delete(id) {
+        const p = this.filePath(id);
+        if (!existsSync(p))
+            return false;
+        rmSync(p, { force: true });
+        return true;
+    }
+    /** Update the secret payload in place (e.g. oauth2 token refresh / exchange completion). */
+    updateData(id, data, metaPatch) {
+        const { summary } = this.get(id);
+        validateCredentialData(summary.type, data);
+        const now = new Date().toISOString();
+        // metaPatch merges into the secret-free meta (undefined deletes the key) — e.g. the OAuth
+        // dance clears `pending` once the token lands, so the UI stops showing 待授权.
+        let meta = summary.meta;
+        if (metaPatch) {
+            meta = { ...(summary.meta ?? {}), ...metaPatch };
+            for (const k of Object.keys(meta))
+                if (meta[k] === undefined)
+                    delete meta[k];
+        }
+        const next = { ...summary, ...(meta !== undefined ? { meta } : {}), updatedAt: now };
+        const envelope = { ...next, enc: this.encrypt(data) };
+        writeFileSync(this.filePath(id), JSON.stringify(envelope, null, 2), { mode: 0o600 });
+        return next;
+    }
+}
+function req(data, key, type) {
+    if (typeof data[key] !== "string" || !data[key]) {
+        throw new Error(`credential(${type}): "${key}" is required`);
+    }
+}
+export function validateCredentialData(type, data) {
+    switch (type) {
+        case "apiKey":
+            req(data, "headerName", type);
+            req(data, "value", type);
+            return;
+        case "bearer":
+            req(data, "token", type);
+            return;
+        case "basic":
+            req(data, "username", type);
+            req(data, "password", type);
+            return;
+        case "oauth2":
+            // accessToken may be absent while the OAuth dance is pending (filled by oauthComplete).
+            return;
+        case "custom":
+            if (typeof data.headers !== "object" || data.headers === null || Array.isArray(data.headers)) {
+                throw new Error(`credential(custom): "headers" object is required`);
+            }
+            return;
+        default: {
+            const _never = type;
+            throw new Error(`credential: unknown type ${JSON.stringify(_never)}`);
+        }
+    }
+}
+/** Materialize a credential into HTTP request headers (the engine-side injection point). */
+export function credentialToHeaders(type, data) {
+    switch (type) {
+        case "apiKey":
+            return { [String(data.headerName)]: String(data.value) };
+        case "bearer":
+            return { Authorization: `Bearer ${String(data.token)}` };
+        case "basic":
+            return { Authorization: `Basic ${Buffer.from(`${String(data.username)}:${String(data.password)}`).toString("base64")}` };
+        case "oauth2": {
+            if (typeof data.accessToken !== "string" || !data.accessToken) {
+                throw new Error("credential(oauth2): no accessToken yet — complete the OAuth authorization first");
+            }
+            return { Authorization: `Bearer ${data.accessToken}` };
+        }
+        case "custom":
+            return { ...data.headers };
+        default: {
+            const _never = type;
+            throw new Error(`credential: unknown type ${JSON.stringify(_never)}`);
+        }
+    }
+}

package/dist/cli/credential-vault.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * IT-7 / D29-D30: credential vault encryption-at-rest + execution-time header injection through a
+ * REAL workflow run against a REAL local HTTP server, plus the per-workflow unattended grant
+ * feeding the permission gate.
+ */
+export {};