@xdxer/dingtalk-agent 0.1.4-beta.8 → 0.1.4-beta.9

package/dist/src/multica-deploy.js

@@ -0,0 +1,1480 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { WORKSPACE_STATE_ROOT, inspectAgentProject, showDevelopmentWorkspace, } from './development-workspace.js';
+import { digest, stableStringify } from './events.js';
+import { MULTICA_BOOT_SKILL, MULTICA_EVIDENCE_ROOT, inspectMulticaWorkspace, planMulticaWorkspace, statusMulticaWorkspace, } from './multica-provider.js';
+import { resolvePackageRoot } from './package-root.js';
+export const MULTICA_DEPLOYMENT_SCHEMA = 'dingtalk-agent/multica-deployment-receipt@1';
+const MAX_DEPLOY_SKILLS = 32;
+const MAX_SKILL_SUPPORTING_FILES = 128;
+const deploymentWriteBudgets = new WeakMap();
+class DeploymentFailure extends Error {
+    category;
+    ambiguous;
+    constructor(category, ambiguous = false) {
+        super(category);
+        this.category = category;
+        this.ambiguous = ambiguous;
+    }
+}
+export function planMulticaDeployment(start, name, options = {}) {
+    const action = options.action || 'apply';
+    const env = options.env || process.env;
+    const cliVersion = options.cliVersion || '';
+    const info = inspectAgentProject(start, cliVersion);
+    const workspace = requireMulticaWorkspace(info.root, name, cliVersion);
+    const source = loadDeploymentSource(info.root);
+    const readPlan = planMulticaWorkspace(info.root, name, { env, cliVersion });
+    const blocking = [...readPlan.blocking];
+    let inspectionId = '';
+    try {
+        const status = statusMulticaWorkspace(info.root, name, cliVersion);
+        inspectionId = status.inspectionId;
+        if (!status.readyForApply || !status.evidenceIntegrity || !status.stateMatched) {
+            blocking.push(...status.failures.map((item) => `inspection.${item}`));
+        }
+    }
+    catch {
+        blocking.push('inspection.invalid');
+    }
+    if (!inspectionId)
+        blocking.push('inspection.missing');
+    if (action === 'retire' && !readPlan.expected.agentId)
+        blocking.push('agent-id.missing');
+    const expectedSkills = source.skills.map((skill) => ({
+        name: skill.name, hash: skill.hash, files: skill.files.length + 1,
+    }));
+    const operations = action === 'retire'
+        ? ['scope.reinspect', 'agent.archive', 'agent.readback', 'receipt.persist']
+        : [
+            'scope.reinspect', 'skills.readback', 'skills.reconcile', 'agent.reconcile',
+            'skills.assign-exact', 'provider.readback', 'load-smoke.create',
+            'load-smoke.readback', 'receipt.persist',
+        ];
+    const writeBudget = action === 'retire'
+        ? { forward: 1, rollback: 0 }
+        : {
+            forward: source.skills.length * (1 + MAX_SKILL_SUPPORTING_FILES * 2) + 4,
+            rollback: source.skills.length * (1 + MAX_SKILL_SUPPORTING_FILES * 2) + 3,
+        };
+    const planId = `multica_deploy_plan_${digest(stableStringify({
+        action, workspace: name, profile: readPlan.profile, inspectionId,
+        desiredHash: workspace.desiredHash, deploymentHash: source.deploymentHash,
+        expected: readPlan.expected, operations, writeBudget,
+        blocking: [...new Set(blocking)].sort(),
+    })).slice(0, 24)}`;
+    return {
+        $schema: 'dingtalk-agent/multica-deployment-plan@1',
+        planId,
+        action,
+        workspace: name,
+        provider: 'multica',
+        profile: readPlan.profile,
+        inspectionId,
+        desiredHash: workspace.desiredHash,
+        deploymentHash: source.deploymentHash,
+        expected: {
+            workspaceId: readPlan.expected.workspaceId,
+            runtimeId: readPlan.expected.runtimeId,
+            agentId: readPlan.expected.agentId,
+            agentName: info.project.name,
+            skills: expectedSkills,
+            definitionHash: source.definitionHash,
+            instructionsHash: source.instructionsHash,
+        },
+        operations,
+        writeBudget,
+        blocking: [...new Set(blocking)].sort(),
+        requiresPlanId: true,
+        requiresExplicitYes: true,
+        remoteRead: false,
+        remoteWrite: false,
+        triggerWrite: false,
+        sideEffect: false,
+        dingtalkSideEffect: false,
+    };
+}
+export function applyMulticaDeployment(start, name, options = {}, action = 'apply') {
+    if (!options.yes) {
+        throw new Error('dta deploy 会修改 Multica 远端资源；必须显式传 --yes 和当前 --plan-id');
+    }
+    if (!options.planId)
+        throw new Error('dta deploy 必须传 dry-run 返回的 --plan-id');
+    const env = options.env || process.env;
+    const cliVersion = options.cliVersion || '';
+    const plan = planMulticaDeployment(start, name, { action, env, cliVersion });
+    if (options.planId !== plan.planId) {
+        throw new Error(`deploy plan 已失效；期望当前 planId ${plan.planId}`);
+    }
+    if (plan.blocking.length)
+        throw new Error(`deploy 前置条件不完整: ${plan.blocking.join(', ')}`);
+    const info = inspectAgentProject(start, cliVersion);
+    const workspace = requireMulticaWorkspace(info.root, name, cliVersion);
+    const source = loadDeploymentSource(info.root);
+    const command = options.command || env.DTA_MULTICA_BIN || 'multica';
+    const timeoutMs = positiveTimeout(options.timeoutMs, 30_000, 300_000);
+    const calls = [];
+    deploymentWriteBudgets.set(calls, plan.writeBudget);
+    const preflight = inspectMulticaWorkspace(info.root, name, {
+        execute: true, yes: true, persist: false, command, env, timeoutMs, cliVersion,
+    });
+    if (!preflight.passed || preflight.inspectionId !== plan.inspectionId ||
+        preflight.profile !== plan.profile ||
+        preflight.expected.workspaceId !== plan.expected.workspaceId ||
+        preflight.expected.runtimeId !== plan.expected.runtimeId) {
+        throw new Error('deploy scope/readback 与冻结 plan 不一致；未执行任何远端写入');
+    }
+    appendInspectionCalls(preflight, 'preflight', calls);
+    const operationId = `multica_operation_${Date.now()}_${randomUUID().slice(0, 12)}`;
+    const operation = createOperation(operationId, plan);
+    operation.calls = [...calls];
+    persistOperation(info.root, operation);
+    const rollback = {
+        createdSkillIds: [], updatedSkills: [], createdAgentId: '', updatedAgent: null,
+        assignmentChanged: false, previousAssignedIds: [],
+    };
+    let receipt;
+    const temp = mkdtempSync(join(tmpdir(), `dta-multica-deploy-${safeName(name)}-`));
+    try {
+        if (action === 'retire') {
+            receipt = retireDeployment(info.root, workspace, source, plan, preflight, operation, command, env, timeoutMs, calls);
+        }
+        else {
+            receipt = executeApply(info.root, workspace, source, plan, preflight, operation, command, env, timeoutMs, positiveTimeout(options.smokeTimeoutMs, 30_000, 60_000), Boolean(options.noWait), calls, rollback, temp);
+        }
+    }
+    catch (error) {
+        const failure = error instanceof DeploymentFailure
+            ? error : new DeploymentFailure('deploy.internal-failure');
+        const rollbackReport = failure.ambiguous
+            ? emptyRollback(false)
+            : rollbackConfirmed(info.root, plan, command, env, timeoutMs, calls, rollback, temp);
+        const status = failure.ambiguous ? 'reconciling' : 'failed';
+        operation.status = status;
+        operation.ambiguousAction = failure.ambiguous ? failure.category : '';
+        operation.calls = calls;
+        operation.failures = [failure.category, ...rollbackReport.failures];
+        operation.updatedAt = new Date().toISOString();
+        receipt = failureReceipt(info.root, workspace, source, plan, preflight, operation, calls, rollbackReport, status, failure.category);
+    }
+    finally {
+        rmSync(temp, { recursive: true, force: true });
+        deploymentWriteBudgets.delete(calls);
+    }
+    persistReceiptAndState(info.root, workspace, operation, receipt);
+    return receipt;
+}
+function executeApply(root, workspace, source, plan, preflight, operation, command, env, timeoutMs, smokeTimeoutMs, noWait, calls, rollback, temp) {
+    const snapshot = readRemoteSnapshot(root, source, preflight, command, env, timeoutMs, calls);
+    const exactBefore = remoteMatchesDesired(snapshot, source, plan.expected.runtimeId);
+    const previous = loadLatestReceipt(root, workspace.name);
+    if (exactBefore && workspace.state?.status === 'ready' &&
+        workspace.state.binding.deploymentHash === source.deploymentHash &&
+        previous?.passed && previous.providerReady && previous.deploymentHash === source.deploymentHash) {
+        const receiptId = `multica_receipt_${digest(stableStringify({
+            operationId: operation.operationId, planId: plan.planId, reuse: previous.receiptId,
+        })).slice(0, 24)}`;
+        return {
+            ...previous,
+            receiptId,
+            operationId: operation.operationId,
+            planId: plan.planId,
+            idempotent: true,
+            calls: [...calls],
+            agent: { ...previous.agent, action: 'noop' },
+            skills: previous.skills.map((skill) => ({ ...skill, action: 'noop' })),
+            evidencePath: receiptRelativePath(workspace.name, receiptId),
+            remoteWrite: false,
+            sideEffect: 'multica-read',
+        };
+    }
+    operation.status = 'applying';
+    operation.calls = calls;
+    operation.updatedAt = new Date().toISOString();
+    persistOperation(root, operation);
+    const skillResults = [];
+    const skillIds = [];
+    for (const local of source.skills) {
+        const remote = snapshot.skills.get(local.name) || null;
+        const result = reconcileSkill(root, plan, local, remote, command, env, timeoutMs, calls, rollback, temp);
+        skillIds.push(result.skill.id);
+        skillResults.push({
+            id: result.skill.id,
+            name: local.name,
+            sourceHash: local.hash,
+            remoteHash: result.skill.hash,
+            action: result.action,
+        });
+    }
+    const agentResult = reconcileAgent(root, plan, source, snapshot.agent, command, env, timeoutMs, calls, rollback);
+    const agentId = agentResult.agent.id;
+    operation.agentId = agentId;
+    const expectedAssignments = [...skillIds].sort();
+    rollback.previousAssignedIds = [...snapshot.assignedIds];
+    if (stableStringify([...snapshot.assignedIds].sort()) !== stableStringify(expectedAssignments)) {
+        runProvider(command, scopedArgs(plan, [
+            'agent', 'skills', 'set', agentId, '--skill-ids', expectedAssignments.join(','), '--output', 'json',
+        ]), 'agent.skills.set', 'write', root, env, timeoutMs, calls);
+        rollback.assignmentChanged = true;
+    }
+    const readback = inspectMulticaWorkspace(root, workspace.name, {
+        execute: true, yes: true, persist: true, command, env, timeoutMs,
+        agentIdOverride: agentId,
+    });
+    if (!readback.passed || !readback.resources.agent ||
+        readback.resources.agent.id !== agentId ||
+        readback.resources.agent.runtimeId !== plan.expected.runtimeId) {
+        throw new DeploymentFailure('readback.agent-mismatch');
+    }
+    const finalSnapshot = readRemoteSnapshot(root, source, readback, command, env, timeoutMs, calls);
+    if (!remoteMatchesDesired(finalSnapshot, source, plan.expected.runtimeId)) {
+        throw new DeploymentFailure('readback.deployment-mismatch');
+    }
+    const observedHash = deploymentObservedHash(finalSnapshot, readback.inspectionId);
+    const smoke = createAndReadSmoke(root, plan, source, agentId, command, env, timeoutMs, smokeTimeoutMs, noWait, calls);
+    const status = smoke.status === 'passed'
+        ? 'ready' : smoke.status === 'pending' ? 'verifying' : 'failed';
+    const receiptId = `multica_receipt_${digest(stableStringify({
+        operationId: operation.operationId, planId: plan.planId, observedHash,
+        smoke: { markerHash: smoke.markerHash, issueId: smoke.issueId, taskId: smoke.taskId },
+    })).slice(0, 24)}`;
+    return {
+        $schema: MULTICA_DEPLOYMENT_SCHEMA,
+        receiptId,
+        operationId: operation.operationId,
+        planId: plan.planId,
+        action: 'apply',
+        workspace: workspace.name,
+        provider: 'multica',
+        profile: plan.profile,
+        status,
+        passed: status === 'ready',
+        providerReady: status === 'ready',
+        idempotent: false,
+        inspectionId: readback.inspectionId,
+        inspectionObservedHash: readback.observedHash,
+        inspectionEvidencePath: readback.evidencePath,
+        desiredHash: workspace.desiredHash,
+        deploymentHash: source.deploymentHash,
+        observedHash,
+        agent: {
+            id: finalSnapshot.agent?.id || agentId,
+            runtimeId: finalSnapshot.agent?.runtimeId || '',
+            instructionsHash: sha256(finalSnapshot.agent?.instructions || ''),
+            archived: Boolean(finalSnapshot.agent?.archived),
+            action: agentResult.action,
+        },
+        skills: skillResults.sort((a, b) => a.name.localeCompare(b.name)),
+        assignmentHash: digest(stableStringify(expectedAssignments)),
+        calls: [...calls],
+        smoke,
+        rollback: emptyRollback(false),
+        failures: [...smoke.failures],
+        evidencePath: receiptRelativePath(workspace.name, receiptId),
+        remoteRead: true,
+        remoteWrite: calls.some((call) => call.kind === 'write'),
+        triggerWrite: false,
+        sideEffect: 'multica-read-write',
+        dingtalkSideEffect: false,
+    };
+}
+function retireDeployment(root, workspace, source, plan, preflight, operation, command, env, timeoutMs, calls) {
+    const agentId = preflight.resources.agent?.id || plan.expected.agentId;
+    if (!agentId)
+        throw new DeploymentFailure('retire.agent-id-missing');
+    if (!preflight.resources.agent?.archived) {
+        runProvider(command, scopedArgs(plan, ['agent', 'archive', agentId, '--output', 'json']), 'agent.archive', 'write', root, env, timeoutMs, calls);
+    }
+    const agent = parseRemoteAgent(jsonObject(runProvider(command, scopedArgs(plan, ['agent', 'get', agentId, '--output', 'json']), 'agent.get.retire-readback', 'read', root, env, timeoutMs, calls).stdout, 'retire agent'));
+    if (!agent.archived || agent.id !== agentId)
+        throw new DeploymentFailure('retire.readback-mismatch');
+    const observedHash = digest(stableStringify({ agentId, archived: true, deploymentHash: source.deploymentHash }));
+    const receiptId = `multica_receipt_${digest(stableStringify({
+        operationId: operation.operationId, action: 'retire', observedHash,
+    })).slice(0, 24)}`;
+    return {
+        $schema: MULTICA_DEPLOYMENT_SCHEMA,
+        receiptId,
+        operationId: operation.operationId,
+        planId: plan.planId,
+        action: 'retire',
+        workspace: workspace.name,
+        provider: 'multica',
+        profile: plan.profile,
+        status: 'retired',
+        passed: true,
+        providerReady: false,
+        idempotent: Boolean(preflight.resources.agent?.archived),
+        inspectionId: preflight.inspectionId,
+        inspectionObservedHash: preflight.observedHash,
+        inspectionEvidencePath: preflight.evidencePath,
+        desiredHash: workspace.desiredHash,
+        deploymentHash: source.deploymentHash,
+        observedHash,
+        agent: {
+            id: agent.id,
+            runtimeId: agent.runtimeId,
+            instructionsHash: sha256(agent.instructions),
+            archived: true,
+            action: preflight.resources.agent?.archived ? 'noop' : 'archive',
+        },
+        skills: [],
+        assignmentHash: '',
+        calls: [...calls],
+        smoke: emptySmoke('not-run', source.skills.map((item) => item.name)),
+        rollback: emptyRollback(false),
+        failures: [],
+        evidencePath: receiptRelativePath(workspace.name, receiptId),
+        remoteRead: true,
+        remoteWrite: calls.some((call) => call.kind === 'write'),
+        triggerWrite: false,
+        sideEffect: 'multica-read-write',
+        dingtalkSideEffect: false,
+    };
+}
+function loadDeploymentSource(root) {
+    const info = inspectAgentProject(root);
+    const definitionPath = safeProjectPath(root, info.project.definition, true);
+    const definition = readUtf8(definitionPath, 'Agent Definition', 512 * 1024);
+    rejectCredentialMaterial(definition, 'Agent Definition');
+    const definitionHash = sha256(definition);
+    const skillRoots = [];
+    for (const name of info.project.skills) {
+        const ref = name === 'dingtalk-basic-behavior'
+            ? `.agents/skills/${name}` : `skills/${name}`;
+        skillRoots.push({ name, root: safeProjectPath(root, ref, true) });
+    }
+    const packageRoot = resolvePackageRoot(import.meta.url);
+    skillRoots.push({
+        name: MULTICA_BOOT_SKILL,
+        root: safeExternalSkillRoot(join(packageRoot, 'skills', MULTICA_BOOT_SKILL)),
+    });
+    if (skillRoots.length > MAX_DEPLOY_SKILLS) {
+        throw new Error(`Multica deploy 最多支持 ${MAX_DEPLOY_SKILLS} 个受管 Skills`);
+    }
+    const skills = skillRoots.map(({ name, root: skillRoot }) => loadSkillBundle(name, skillRoot))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    if (new Set(skills.map((item) => item.name)).size !== skills.length) {
+        throw new Error('Multica deploy required Skills 不能重名');
+    }
+    const required = skills.map((item) => ({ name: item.name, sha256: item.hash }));
+    const deploymentSourceHash = digest(stableStringify({ definitionHash, required }));
+    const instructions = [
+        '<!-- DTA Multica Boot: managed; do not edit remotely -->',
+        `definition_sha256=${definitionHash}`,
+        `deployment_sha256=${deploymentSourceHash}`,
+        `required_skills=${JSON.stringify(required)}`,
+        'Before every task, use dingtalk-agent-boot-multica and follow its startup order.',
+        'Never create a robot, webhook, autopilot, schedule, or other Trigger as part of deployment.',
+        '<!-- /DTA Multica Boot -->',
+        '',
+        definition.trimEnd(),
+        '',
+    ].join('\n');
+    const instructionsHash = sha256(instructions);
+    const deploymentHash = digest(stableStringify({
+        definitionHash, instructionsHash,
+        skills: skills.map((item) => ({ name: item.name, hash: item.hash })),
+    }));
+    return { definition, definitionHash, instructions, instructionsHash, skills, deploymentHash };
+}
+function loadSkillBundle(name, root) {
+    const actual = realpathSync(root);
+    if (!lstatSync(actual).isDirectory())
+        throw new Error(`Skill ${name} source 不是目录`);
+    const files = [];
+    const visit = (directory, prefix = '') => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })
+            .sort((a, b) => a.name.localeCompare(b.name))) {
+            const path = join(directory, entry.name);
+            const ref = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isSymbolicLink())
+                throw new Error(`Skill ${name} 不允许符号链接: ${ref}`);
+            if (entry.isDirectory())
+                visit(path, ref);
+            else if (entry.isFile()) {
+                const content = readFileSync(path);
+                if (content.length > 1024 * 1024)
+                    throw new Error(`Skill ${name} 文件超过 1 MiB: ${ref}`);
+                const text = content.toString('utf8');
+                if (Buffer.from(text, 'utf8').compare(content) !== 0 || content.includes(0)) {
+                    throw new Error(`Skill ${name} 只支持 UTF-8 supporting files: ${ref}`);
+                }
+                rejectCredentialMaterial(text, `Skill ${name}/${ref}`);
+                files.push({ path: ref, absolutePath: path, hash: sha256(content), bytes: content.length });
+                if (files.length > MAX_SKILL_SUPPORTING_FILES + 1) {
+                    throw new Error(`Skill ${name} files 超过 ${MAX_SKILL_SUPPORTING_FILES + 1} 个`);
+                }
+            }
+            else
+                throw new Error(`Skill ${name} 包含特殊文件: ${ref}`);
+        }
+    };
+    visit(actual);
+    if (files.reduce((sum, item) => sum + item.bytes, 0) > 8 * 1024 * 1024) {
+        throw new Error(`Skill ${name} 总大小超过 8 MiB`);
+    }
+    const main = files.find((item) => item.path === 'SKILL.md');
+    if (!main)
+        throw new Error(`Skill ${name} 缺少 SKILL.md`);
+    const content = readUtf8(main.absolutePath, `Skill ${name}`, 1024 * 1024);
+    const declared = frontmatterName(content);
+    if (declared !== name)
+        throw new Error(`Skill ${name} frontmatter name 不一致: ${declared || '<missing>'}`);
+    rejectCredentialMaterial(content, `Skill ${name}`);
+    const supporting = files.filter((item) => item.path !== 'SKILL.md');
+    if (supporting.length > MAX_SKILL_SUPPORTING_FILES) {
+        throw new Error(`Skill ${name} supporting files 超过 ${MAX_SKILL_SUPPORTING_FILES} 个`);
+    }
+    const hash = skillTreeHash(content, supporting.map((item) => ({ path: item.path, hash: item.hash })));
+    return { name, root: actual, mainPath: main.absolutePath, content, files: supporting, hash };
+}
+function readRemoteSnapshot(root, source, inspection, command, env, timeoutMs, calls) {
+    const planLike = {
+        profile: inspection.profile,
+        expected: inspection.expected,
+    };
+    const skills = new Map();
+    for (const local of source.skills) {
+        const candidates = inspection.resources.catalogSkills.filter((item) => item.name === local.name);
+        if (candidates.length > 1)
+            throw new DeploymentFailure(`skills.duplicate:${local.name}`);
+        if (!candidates.length) {
+            skills.set(local.name, null);
+            continue;
+        }
+        const raw = jsonObject(runProvider(command, scopedArgs(planLike, ['skill', 'get', candidates[0].id, '--output', 'json']), `skill.get:${local.name}`, 'read', root, env, timeoutMs, calls).stdout, `skill ${local.name}`);
+        const skill = parseRemoteSkill(raw);
+        if (skill.id !== candidates[0].id || skill.name !== local.name) {
+            throw new DeploymentFailure(`skills.binding-mismatch:${local.name}`);
+        }
+        skills.set(local.name, skill);
+    }
+    let agent = null;
+    if (inspection.resources.agent) {
+        agent = parseRemoteAgent(jsonObject(runProvider(command, scopedArgs(planLike, [
+            'agent', 'get', inspection.resources.agent.id, '--output', 'json',
+        ]), 'agent.get.deploy', 'read', root, env, timeoutMs, calls).stdout, 'agent deploy'));
+        if (agent.id !== inspection.resources.agent.id)
+            throw new DeploymentFailure('agent.binding-mismatch');
+    }
+    return {
+        agent,
+        skills,
+        assignedIds: inspection.resources.assignedSkills.filter((item) => item.enabled)
+            .map((item) => item.id).sort(),
+    };
+}
+function reconcileSkill(root, plan, local, remote, command, env, timeoutMs, calls, rollback, temp) {
+    let id = remote?.id || '';
+    let action = 'noop';
+    if (!remote) {
+        const created = jsonObject(runProvider(command, scopedArgs(plan, [
+            'skill', 'create', '--name', local.name,
+            '--description', `Managed by dingtalk-agent (${local.hash.slice(0, 12)})`,
+            '--content-file', local.mainPath, '--output', 'json',
+        ]), `skill.create:${local.name}`, 'write', root, env, timeoutMs, calls).stdout, `created skill ${local.name}`);
+        id = resourceId(created.id, `created skill ${local.name}.id`);
+        rollback.createdSkillIds.push(id);
+        action = 'create';
+        for (const file of local.files)
+            upsertSkillFile(root, plan, id, file.path, file.absolutePath, command, env, timeoutMs, calls);
+    }
+    else if (remote.hash !== local.hash) {
+        rollback.updatedSkills.push(remote);
+        runProvider(command, scopedArgs(plan, [
+            'skill', 'update', id, '--content-file', local.mainPath, '--output', 'json',
+        ]), `skill.update:${local.name}`, 'write', root, env, timeoutMs, calls);
+        syncSkillFiles(root, plan, id, local, remote, command, env, timeoutMs, calls);
+        action = 'update';
+    }
+    const readback = parseRemoteSkill(jsonObject(runProvider(command, scopedArgs(plan, ['skill', 'get', id, '--output', 'json']), `skill.get.readback:${local.name}`, 'read', root, env, timeoutMs, calls).stdout, `skill readback ${local.name}`));
+    if (readback.name !== local.name || readback.hash !== local.hash) {
+        throw new DeploymentFailure(`skill.readback-mismatch:${local.name}`);
+    }
+    return { skill: readback, action };
+}
+function reconcileAgent(root, plan, source, remote, command, env, timeoutMs, calls, rollback) {
+    let id = remote?.id || '';
+    let action = 'noop';
+    if (!remote) {
+        const created = jsonObject(runProvider(command, scopedArgs(plan, [
+            'agent', 'create', '--name', plan.expected.agentName,
+            '--description', `Managed dingtalk-agent ${plan.deploymentHash.slice(0, 12)}`,
+            '--instructions', source.instructions,
+            '--runtime-id', plan.expected.runtimeId,
+            '--permission-mode', 'private', '--output', 'json',
+        ]), 'agent.create', 'write', root, env, timeoutMs, calls).stdout, 'created agent');
+        id = resourceId(created.id, 'created agent.id');
+        rollback.createdAgentId = id;
+        action = 'create';
+    }
+    else {
+        if (remote.archived) {
+            rollback.updatedAgent = remote;
+            runProvider(command, scopedArgs(plan, ['agent', 'restore', id, '--output', 'json']), 'agent.restore', 'write', root, env, timeoutMs, calls);
+            action = 'restore';
+        }
+        if (remote.name !== plan.expected.agentName || remote.runtimeId !== plan.expected.runtimeId ||
+            remote.instructions !== source.instructions) {
+            rollback.updatedAgent ||= remote;
+            runProvider(command, scopedArgs(plan, [
+                'agent', 'update', id, '--name', plan.expected.agentName,
+                '--instructions', source.instructions, '--runtime-id', plan.expected.runtimeId,
+                '--output', 'json',
+            ]), 'agent.update', 'write', root, env, timeoutMs, calls);
+            action = action === 'restore' ? 'restore' : 'update';
+        }
+    }
+    const agent = parseRemoteAgent(jsonObject(runProvider(command, scopedArgs(plan, ['agent', 'get', id, '--output', 'json']), 'agent.get.readback', 'read', root, env, timeoutMs, calls).stdout, 'agent readback'));
+    if (agent.id !== id || agent.name !== plan.expected.agentName ||
+        agent.runtimeId !== plan.expected.runtimeId || agent.instructions !== source.instructions || agent.archived) {
+        throw new DeploymentFailure('agent.readback-mismatch');
+    }
+    return { agent, action };
+}
+function syncSkillFiles(root, plan, skillId, local, remote, command, env, timeoutMs, calls) {
+    const remoteByPath = new Map(remote.files.map((item) => [item.path, item]));
+    const localPaths = new Set(local.files.map((item) => item.path));
+    for (const file of remote.files) {
+        if (localPaths.has(file.path))
+            continue;
+        runProvider(command, scopedArgs(plan, ['skill', 'files', 'delete', skillId, file.id]), `skill.file.delete:${local.name}:${file.path}`, 'write', root, env, timeoutMs, calls);
+    }
+    for (const file of local.files) {
+        if (remoteByPath.get(file.path)?.hash === file.hash)
+            continue;
+        upsertSkillFile(root, plan, skillId, file.path, file.absolutePath, command, env, timeoutMs, calls);
+    }
+}
+function upsertSkillFile(root, plan, skillId, path, contentFile, command, env, timeoutMs, calls) {
+    runProvider(command, scopedArgs(plan, [
+        'skill', 'files', 'upsert', skillId, '--path', path,
+        '--content-file', contentFile, '--output', 'json',
+    ]), `skill.file.upsert:${path}`, 'write', root, env, timeoutMs, calls);
+}
+function createAndReadSmoke(root, plan, source, agentId, command, env, timeoutMs, smokeTimeoutMs, noWait, calls) {
+    const marker = `DTA-MULTICA-LOAD-${randomUUID()}`;
+    const requiredSkills = source.skills.map((item) => item.name).sort();
+    const issue = jsonObject(runProvider(command, scopedArgs(plan, [
+        'issue', 'create', '--title', `[DTA load smoke] ${marker}`,
+        '--description', [
+            'DTA_MULTICA_LOAD_SMOKE@1', `marker=${marker}`,
+            'Use only the trusted DTA Multica Boot required_skills list.',
+            'Do not call DWS, Shell, network, or write tools.',
+        ].join('\n'),
+        '--assignee-id', agentId, '--output', 'json',
+    ]), 'smoke.issue.create', 'write', root, env, timeoutMs, calls).stdout, 'smoke issue');
+    const issueId = resourceId(issue.id, 'smoke issue.id');
+    if (noWait)
+        return readSmoke(root, plan, marker, issueId, agentId, requiredSkills, command, env, timeoutMs, calls);
+    const started = Date.now();
+    let smoke = readSmoke(root, plan, marker, issueId, agentId, requiredSkills, command, env, timeoutMs, calls);
+    while (smoke.status === 'pending' && Date.now() - started < smokeTimeoutMs) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 250);
+        smoke = readSmoke(root, plan, marker, issueId, agentId, requiredSkills, command, env, timeoutMs, calls);
+    }
+    return smoke;
+}
+function readSmoke(root, plan, marker, issueId, agentId, requiredSkills, command, env, timeoutMs, calls) {
+    const runs = jsonArray(runProvider(command, scopedArgs(plan, ['issue', 'runs', issueId, '--full-id', '--output', 'json']), 'smoke.issue.runs', 'read', root, env, timeoutMs, calls).stdout, 'smoke runs');
+    const candidates = runs.filter((item) => !optionalString(item.agent_id) ||
+        optionalString(item.agent_id) === agentId);
+    const run = candidates.sort((a, b) => optionalString(b.created_at).localeCompare(optionalString(a.created_at)))[0];
+    if (!run)
+        return {
+            ...emptySmoke('pending', requiredSkills), marker, markerHash: sha256(marker), issueId,
+        };
+    const taskId = resourceId(run.id, 'smoke task.id');
+    const taskStatus = optionalString(run.status);
+    if (!['completed', 'failed', 'cancelled'].includes(taskStatus))
+        return {
+            ...emptySmoke('pending', requiredSkills), marker, markerHash: sha256(marker), issueId, taskId, taskStatus,
+        };
+    const messages = jsonArray(runProvider(command, scopedArgs(plan, [
+        'issue', 'run-messages', taskId, '--issue', issueId, '--output', 'json',
+    ]), 'smoke.issue.messages', 'read', root, env, timeoutMs, calls).stdout, 'smoke messages');
+    const toolUses = messages.filter((item) => optionalString(item.type) === 'tool_use');
+    const nonSkillTools = toolUses.filter((item) => !/skill/i.test(optionalString(item.tool)));
+    const loadedSkills = requiredSkills.filter((name) => toolUses.some((item) => JSON.stringify(item.input || {}).includes(name))).sort();
+    const texts = messages.filter((item) => optionalString(item.type) === 'text')
+        .map((item) => optionalString(item.content)).filter(Boolean);
+    const finalText = texts.at(-1) || '';
+    let responsePassed = false;
+    try {
+        const parsed = JSON.parse(finalText);
+        responsePassed = parsed?.schema === 'dta-multica-load-smoke@1' &&
+            parsed?.marker === marker &&
+            stableStringify(Array.isArray(parsed?.loaded) ? [...parsed.loaded].sort() : []) ===
+                stableStringify(requiredSkills);
+    }
+    catch {
+        responsePassed = false;
+    }
+    const toolTracePassed = nonSkillTools.length === 0 &&
+        stableStringify(loadedSkills) === stableStringify(requiredSkills);
+    const failures = [];
+    if (taskStatus !== 'completed')
+        failures.push(`smoke.task.${taskStatus || 'unknown'}`);
+    if (!toolTracePassed)
+        failures.push('smoke.skill-tool-trace');
+    if (!responsePassed)
+        failures.push('smoke.response');
+    return {
+        status: failures.length ? 'failed' : 'passed',
+        marker, markerHash: sha256(marker), issueId, taskId, taskStatus, requiredSkills, loadedSkills,
+        toolTracePassed, responsePassed, responseHash: sha256(finalText), failures,
+    };
+}
+function rollbackConfirmed(root, plan, command, env, timeoutMs, calls, rollback, temp) {
+    const report = emptyRollback(true);
+    const attempt = (id, argv) => {
+        try {
+            runProvider(command, scopedArgs(plan, argv), id, 'rollback', root, env, timeoutMs, calls);
+            report.actions.push(id);
+        }
+        catch {
+            report.failures.push(id);
+        }
+    };
+    const assignmentAgentId = rollback.createdAgentId || rollback.updatedAgent?.id || '';
+    if (rollback.assignmentChanged && assignmentAgentId) {
+        attempt('rollback.agent.skills', [
+            'agent', 'skills', 'set', assignmentAgentId,
+            '--skill-ids', rollback.previousAssignedIds.join(','), '--output', 'json',
+        ]);
+    }
+    if (rollback.createdAgentId) {
+        attempt('rollback.agent.archive', ['agent', 'archive', rollback.createdAgentId, '--output', 'json']);
+    }
+    else if (rollback.updatedAgent) {
+        const previous = rollback.updatedAgent;
+        const argv = [
+            'agent', 'update', previous.id, '--name', previous.name,
+            '--instructions', previous.instructions, '--runtime-id', previous.runtimeId,
+        ];
+        if (previous.status)
+            argv.push('--status', previous.status);
+        argv.push('--output', 'json');
+        attempt('rollback.agent.update', argv);
+        if (previous.archived) {
+            attempt('rollback.agent.archive', ['agent', 'archive', previous.id, '--output', 'json']);
+        }
+    }
+    for (const previous of [...rollback.updatedSkills].reverse()) {
+        const main = writeTemporaryContent(temp, `${previous.id}-SKILL.md`, previous.content);
+        attempt(`rollback.skill.update:${previous.name}`, [
+            'skill', 'update', previous.id, '--content-file', main, '--output', 'json',
+        ]);
+        try {
+            const current = parseRemoteSkill(jsonObject(runProvider(command, scopedArgs(plan, ['skill', 'get', previous.id, '--output', 'json']), `rollback.skill.get:${previous.name}`, 'read', root, env, timeoutMs, calls).stdout, `rollback skill ${previous.name}`));
+            const previousPaths = new Set(previous.files.map((file) => file.path));
+            for (const extra of current.files.filter((file) => !previousPaths.has(file.path))) {
+                attempt(`rollback.skill.file.delete:${previous.name}:${extra.path}`, [
+                    'skill', 'files', 'delete', previous.id, extra.id,
+                ]);
+            }
+        }
+        catch {
+            report.failures.push(`rollback.skill.verify:${previous.name}`);
+        }
+        for (const file of previous.files) {
+            const path = writeTemporaryContent(temp, `${previous.id}-${sha256(file.path).slice(0, 8)}`, file.content);
+            attempt(`rollback.skill.file:${previous.name}:${file.path}`, [
+                'skill', 'files', 'upsert', previous.id, '--path', file.path,
+                '--content-file', path, '--output', 'json',
+            ]);
+        }
+    }
+    for (const id of [...rollback.createdSkillIds].reverse()) {
+        attempt(`rollback.skill.delete:${id}`, ['skill', 'delete', id, '--yes']);
+    }
+    verifyRollback(root, plan, command, env, timeoutMs, calls, rollback, report);
+    report.passed = report.failures.length === 0;
+    return report;
+}
+function verifyRollback(root, plan, command, env, timeoutMs, calls, rollback, report) {
+    const verify = (id, action) => {
+        try {
+            if (!action())
+                report.failures.push(id);
+        }
+        catch {
+            report.failures.push(id);
+        }
+    };
+    if (rollback.createdSkillIds.length || rollback.updatedSkills.length) {
+        verify('rollback.verify.skills', () => {
+            const catalog = jsonArray(runProvider(command, scopedArgs(plan, ['skill', 'list', '--output', 'json']), 'rollback.verify.skill-list', 'read', root, env, timeoutMs, calls).stdout, 'rollback skill list');
+            const ids = new Set(catalog.map((item) => resourceId(item.id, 'rollback skill.id')));
+            return rollback.createdSkillIds.every((id) => !ids.has(id));
+        });
+        for (const previous of rollback.updatedSkills) {
+            verify(`rollback.verify.skill:${previous.name}`, () => {
+                const restored = parseRemoteSkill(jsonObject(runProvider(command, scopedArgs(plan, ['skill', 'get', previous.id, '--output', 'json']), `rollback.verify.skill-get:${previous.name}`, 'read', root, env, timeoutMs, calls).stdout, `rollback verify skill ${previous.name}`));
+                return restored.id === previous.id && restored.name === previous.name &&
+                    restored.hash === previous.hash;
+            });
+        }
+    }
+    const agentId = rollback.createdAgentId || rollback.updatedAgent?.id || '';
+    if (!agentId)
+        return;
+    verify('rollback.verify.agent', () => {
+        const restored = parseRemoteAgent(jsonObject(runProvider(command, scopedArgs(plan, ['agent', 'get', agentId, '--output', 'json']), 'rollback.verify.agent-get', 'read', root, env, timeoutMs, calls).stdout, 'rollback verify agent'));
+        if (rollback.createdAgentId)
+            return restored.archived;
+        const previous = rollback.updatedAgent;
+        return Boolean(previous && restored.id === previous.id && restored.name === previous.name &&
+            restored.runtimeId === previous.runtimeId && restored.instructions === previous.instructions &&
+            restored.archived === previous.archived);
+    });
+    if (rollback.assignmentChanged) {
+        verify('rollback.verify.assignment', () => {
+            const assigned = jsonArray(runProvider(command, scopedArgs(plan, [
+                'agent', 'skills', 'list', agentId, '--output', 'json',
+            ]), 'rollback.verify.agent-skills', 'read', root, env, timeoutMs, calls).stdout, 'rollback verify assignments');
+            const ids = assigned.map((item) => resourceId(item.id, 'rollback assignment.id')).sort();
+            return stableStringify(ids) === stableStringify([...rollback.previousAssignedIds].sort());
+        });
+    }
+}
+function failureReceipt(root, workspace, source, plan, preflight, operation, calls, rollback, status, failure) {
+    const receiptId = `multica_receipt_${digest(stableStringify({
+        operationId: operation.operationId, status, failure,
+    })).slice(0, 24)}`;
+    return {
+        $schema: MULTICA_DEPLOYMENT_SCHEMA,
+        receiptId,
+        operationId: operation.operationId,
+        planId: plan.planId,
+        action: plan.action,
+        workspace: workspace.name,
+        provider: 'multica',
+        profile: plan.profile,
+        status,
+        passed: false,
+        providerReady: false,
+        idempotent: false,
+        inspectionId: preflight.inspectionId,
+        inspectionObservedHash: preflight.observedHash,
+        inspectionEvidencePath: preflight.evidencePath,
+        desiredHash: workspace.desiredHash,
+        deploymentHash: source.deploymentHash,
+        observedHash: '',
+        agent: {
+            id: operation.agentId,
+            runtimeId: plan.expected.runtimeId,
+            instructionsHash: source.instructionsHash,
+            archived: false,
+            action: 'unknown',
+        },
+        skills: source.skills.map((item) => ({
+            id: '', name: item.name, sourceHash: item.hash, remoteHash: '', action: 'unknown',
+        })),
+        assignmentHash: '',
+        calls: [...calls],
+        smoke: emptySmoke('not-run', source.skills.map((item) => item.name)),
+        rollback,
+        failures: [failure, ...rollback.failures],
+        evidencePath: receiptRelativePath(workspace.name, receiptId),
+        remoteRead: true,
+        remoteWrite: calls.some((call) => call.kind === 'write' || call.kind === 'rollback'),
+        triggerWrite: false,
+        sideEffect: calls.some((call) => call.kind === 'write' || call.kind === 'rollback')
+            ? 'multica-read-write' : 'multica-read',
+        dingtalkSideEffect: false,
+    };
+}
+export function statusMulticaDeployment(start, name, options = {}) {
+    const info = inspectAgentProject(start, options.cliVersion || '');
+    requireMulticaWorkspace(info.root, name, options.cliVersion || '');
+    const loaded = loadOperationAndReceipt(info.root, name, options.operationId);
+    if (!loaded)
+        return {
+            $schema: 'dingtalk-agent/multica-deployment-status@1',
+            workspace: name, provider: 'multica', available: false, operationId: '', receiptId: '',
+            status: 'missing', passed: false, providerReady: false,
+            operationIntegrity: false, receiptIntegrity: false, reconciled: false,
+            failures: ['deployment.missing'], receipt: null,
+            remoteRead: false, remoteWrite: false, triggerWrite: false,
+            sideEffect: false, dingtalkSideEffect: false,
+        };
+    let { operation, receipt } = loaded;
+    let reconciled = false;
+    let remoteRead = false;
+    if (options.execute) {
+        if (!options.yes)
+            throw new Error('deploy --status 远端 reconcile 必须同时传 --execute --yes');
+        const command = options.command || options.env?.DTA_MULTICA_BIN || process.env.DTA_MULTICA_BIN || 'multica';
+        const env = options.env || process.env;
+        const timeoutMs = positiveTimeout(options.timeoutMs, 30_000, 300_000);
+        if (receipt.status === 'verifying' && receipt.smoke.issueId) {
+            remoteRead = true;
+            const smokeReadback = readSmokeFromReceipt(info.root, receipt, command, env, timeoutMs);
+            const smoke = smokeReadback.smoke;
+            receipt = { ...receipt, calls: smokeReadback.calls, smoke, status: smoke.status === 'passed' ? 'ready'
+                    : smoke.status === 'pending' ? 'verifying' : 'failed',
+                passed: smoke.status === 'passed', providerReady: smoke.status === 'passed',
+                failures: [...smoke.failures] };
+            reconciled = true;
+            persistReceiptAndState(info.root, showDevelopmentWorkspace(info.root, name), operation, receipt);
+        }
+        else if (receipt.status === 'reconciling') {
+            remoteRead = true;
+            const source = loadDeploymentSource(info.root);
+            const calls = [...receipt.calls];
+            const reconciledTarget = reconcileRemoteTarget(info.root, name, operation, source, command, env, timeoutMs, calls);
+            const inspection = reconciledTarget.inspection;
+            const snapshot = reconciledTarget.snapshot;
+            const matched = Boolean(snapshot && remoteMatchesDesired(snapshot, source, operation.runtimeId));
+            const safelyBound = Boolean(snapshot?.agent && inspection.passed &&
+                snapshot.agent.id === operation.agentId &&
+                snapshot.agent.name === info.project.name &&
+                snapshot.agent.runtimeId === operation.runtimeId &&
+                snapshot.agent.instructions === source.instructions && !snapshot.agent.archived);
+            receipt = { ...receipt,
+                calls,
+                inspectionId: inspection.inspectionId,
+                inspectionObservedHash: inspection.observedHash,
+                inspectionEvidencePath: inspection.evidencePath,
+                agent: { ...receipt.agent, id: operation.agentId },
+                status: matched || safelyBound ? 'verifying' : 'failed',
+                failures: matched ? ['smoke.required-after-recovery']
+                    : safelyBound ? ['apply.required-after-recovery']
+                        : reconciledTarget.failures.length ? reconciledTarget.failures
+                            : inspection.passed ? ['reconcile.remote-mismatch'] : [...inspection.failures],
+            };
+            reconciled = true;
+            persistReceiptAndState(info.root, showDevelopmentWorkspace(info.root, name), operation, receipt);
+        }
+        operation = loadOperationAndReceipt(info.root, name, operation.operationId)?.operation || operation;
+    }
+    return {
+        $schema: 'dingtalk-agent/multica-deployment-status@1',
+        workspace: name,
+        provider: 'multica',
+        available: true,
+        operationId: operation.operationId,
+        receiptId: receipt.receiptId,
+        status: receipt.status,
+        passed: receipt.passed,
+        providerReady: receipt.providerReady,
+        operationIntegrity: true,
+        receiptIntegrity: true,
+        reconciled,
+        failures: [...receipt.failures],
+        receipt,
+        remoteRead,
+        remoteWrite: false,
+        triggerWrite: false,
+        sideEffect: remoteRead ? 'multica-read' : false,
+        dingtalkSideEffect: false,
+    };
+}
+export function listMulticaDeployments(start, name, cliVersion = '') {
+    const info = inspectAgentProject(start, cliVersion);
+    requireMulticaWorkspace(info.root, name, cliVersion);
+    const directory = safeProjectPath(info.root, receiptsRoot(name), false);
+    const deployments = [];
+    if (existsSync(directory)) {
+        for (const entry of readdirSync(directory, { withFileTypes: true })
+            .filter((item) => item.isFile() && item.name.endsWith('.json'))
+            .sort((a, b) => b.name.localeCompare(a.name))) {
+            const path = join(directory, entry.name);
+            if (lstatSync(path).isSymbolicLink())
+                throw new Error('Multica Receipt 不能是符号链接');
+            const candidate = parseReceipt(readJson(path, 'Multica Receipt'));
+            const loaded = loadOperationAndReceipt(info.root, name, candidate.operationId);
+            if (!loaded || loaded.receipt.receiptId !== candidate.receiptId ||
+                safeProjectPath(info.root, loaded.receipt.evidencePath, true) !== path) {
+                throw new Error('Multica deployment 历史 Receipt 绑定不一致');
+            }
+            const receipt = loaded.receipt;
+            deployments.push({
+                receiptId: receipt.receiptId,
+                operationId: receipt.operationId,
+                action: receipt.action,
+                status: receipt.status,
+                passed: receipt.passed,
+                providerReady: receipt.providerReady,
+                planId: receipt.planId,
+                deploymentHash: receipt.deploymentHash,
+            });
+        }
+    }
+    return {
+        $schema: 'dingtalk-agent/multica-deployment-list@1',
+        workspace: name, provider: 'multica', deployments,
+        remoteRead: false, remoteWrite: false, triggerWrite: false,
+        sideEffect: false, dingtalkSideEffect: false,
+    };
+}
+function reconcileRemoteTarget(root, name, operation, source, command, env, timeoutMs, calls) {
+    if (operation.agentId) {
+        const inspection = inspectMulticaWorkspace(root, name, {
+            execute: true, yes: true, persist: true, command, env, timeoutMs,
+            agentIdOverride: operation.agentId,
+        });
+        appendInspectionCalls(inspection, 'reconcile.scope', calls);
+        const snapshot = inspection.passed ? readRemoteSnapshot(root, source, inspection, command, env, timeoutMs, calls) : null;
+        return { inspection, snapshot, failures: [] };
+    }
+    const discovery = inspectMulticaWorkspace(root, name, {
+        execute: true, yes: true, persist: false, command, env, timeoutMs,
+    });
+    appendInspectionCalls(discovery, 'reconcile.discovery', calls);
+    const candidates = discovery.resources.agentCandidates;
+    if (!candidates.length) {
+        return { inspection: discovery, snapshot: null, failures: ['reconcile.agent-not-found'] };
+    }
+    if (candidates.length > 10) {
+        return { inspection: discovery, snapshot: null, failures: ['reconcile.agent-candidate-budget'] };
+    }
+    const projectName = inspectAgentProject(root).project.name;
+    const matches = [];
+    for (const [index, candidate] of candidates.entries()) {
+        const inspection = inspectMulticaWorkspace(root, name, {
+            execute: true, yes: true, persist: false, command, env, timeoutMs,
+            agentIdOverride: candidate.id,
+        });
+        appendInspectionCalls(inspection, `reconcile.candidate.${index + 1}`, calls);
+        if (!inspection.passed)
+            continue;
+        const snapshot = readRemoteSnapshot(root, source, inspection, command, env, timeoutMs, calls);
+        if (snapshot.agent && snapshot.agent.id === candidate.id &&
+            snapshot.agent.name === projectName && snapshot.agent.runtimeId === operation.runtimeId &&
+            snapshot.agent.instructions === source.instructions && !snapshot.agent.archived) {
+            matches.push({ id: candidate.id });
+        }
+    }
+    if (matches.length !== 1) {
+        return {
+            inspection: discovery,
+            snapshot: null,
+            failures: [matches.length ? 'reconcile.agent-ambiguous' : 'reconcile.agent-fingerprint-mismatch'],
+        };
+    }
+    operation.agentId = matches[0].id;
+    const inspection = inspectMulticaWorkspace(root, name, {
+        execute: true, yes: true, persist: true, command, env, timeoutMs,
+        agentIdOverride: operation.agentId,
+    });
+    appendInspectionCalls(inspection, 'reconcile.bound', calls);
+    const snapshot = inspection.passed ? readRemoteSnapshot(root, source, inspection, command, env, timeoutMs, calls) : null;
+    return { inspection, snapshot, failures: inspection.passed ? [] : [...inspection.failures] };
+}
+function appendInspectionCalls(inspection, prefix, calls) {
+    calls.push(...inspection.calls.map((call) => ({
+        id: `${prefix}.${call.id}`,
+        kind: 'read',
+        argv: [...call.argv],
+        exitCode: call.exitCode,
+        stdoutHash: call.stdoutHash,
+        stderrHash: call.stderrHash,
+        passed: call.passed,
+        ambiguous: false,
+    })));
+}
+function readSmokeFromReceipt(root, receipt, command, env, timeoutMs) {
+    const plan = {
+        profile: receipt.profile,
+        expected: { workspaceId: '', runtimeId: receipt.agent.runtimeId },
+    };
+    const operation = loadOperationAndReceipt(root, receipt.workspace, receipt.operationId)?.operation;
+    if (!operation)
+        throw new Error('Multica deployment operation 缺失');
+    plan.expected.workspaceId = operation.workspaceId;
+    const calls = [...receipt.calls];
+    const markerValue = receipt.smoke.marker;
+    if (!markerValue || sha256(markerValue) !== receipt.smoke.markerHash) {
+        return { calls, smoke: {
+                ...receipt.smoke,
+                status: 'failed',
+                failures: ['smoke.marker-not-recoverable'],
+            } };
+    }
+    const smoke = readSmoke(root, plan, markerValue, receipt.smoke.issueId, receipt.agent.id, receipt.smoke.requiredSkills, command, env, timeoutMs, calls);
+    return { smoke, calls };
+}
+function persistReceiptAndState(root, workspace, operation, receipt) {
+    assertReportRedacted(receipt);
+    const receiptPath = safeProjectPath(root, receipt.evidencePath, false);
+    atomicJson(receiptPath, receipt);
+    const receiptHash = sha256(readFileSync(receiptPath));
+    operation.status = receipt.status;
+    operation.agentId = receipt.agent.id || operation.agentId;
+    operation.receiptId = receipt.receiptId;
+    operation.receiptPath = receipt.evidencePath;
+    operation.calls = receipt.calls;
+    operation.failures = receipt.failures;
+    operation.updatedAt = new Date().toISOString();
+    persistOperation(root, operation);
+    const operationPath = operationRelativePath(workspace.name, operation.operationId);
+    const operationHash = sha256(readFileSync(safeProjectPath(root, operationPath, true)));
+    const binding = {
+        $schema: 'dingtalk-agent/multica-deployment-pointer@1',
+        operationId: operation.operationId,
+        operationPath,
+        operationHash,
+        receiptId: receipt.receiptId,
+        receiptPath: receipt.evidencePath,
+        receiptHash,
+    };
+    atomicJson(safeProjectPath(root, operationBindingPath(workspace.name, operation.operationId), false), binding);
+    atomicJson(safeProjectPath(root, latestDeploymentPointer(workspace.name), false), binding);
+    const stateStatus = receipt.status === 'ready' ? 'ready'
+        : receipt.status === 'retired' ? 'retired'
+            : receipt.status === 'failed' ? 'failed' : 'verifying';
+    const state = {
+        $schema: 'dingtalk-agent/workspace-state@1',
+        workspace: workspace.name,
+        provider: 'multica',
+        status: stateStatus,
+        binding: {
+            ...(workspace.state?.binding || {}),
+            profile: receipt.profile,
+            remoteWorkspaceId: operation.workspaceId,
+            runtimeId: operation.runtimeId,
+            agentId: receipt.agent.id || operation.agentId,
+            deploymentHash: receipt.deploymentHash,
+            inspectionId: receipt.inspectionId,
+            inspectionObservedHash: receipt.inspectionObservedHash,
+            inspectionEvidencePath: receipt.inspectionEvidencePath,
+            receiptPath: receipt.evidencePath,
+            operationId: operation.operationId,
+            sourceHash: workspace.sourceHash,
+        },
+        desiredHash: workspace.desiredHash,
+        observedHash: receipt.inspectionObservedHash || receipt.observedHash,
+        lastPlanId: receipt.planId,
+        lastReceiptId: receipt.receiptId,
+        lastEvalId: receipt.smoke.taskId,
+    };
+    atomicJson(safeProjectPath(root, join(WORKSPACE_STATE_ROOT, `${workspace.name}.json`), false), state);
+}
+function createOperation(operationId, plan) {
+    return {
+        $schema: 'dingtalk-agent/multica-deployment-operation@1',
+        operationId,
+        planId: plan.planId,
+        workspace: plan.workspace,
+        action: plan.action,
+        status: 'applying',
+        profile: plan.profile,
+        workspaceId: plan.expected.workspaceId,
+        runtimeId: plan.expected.runtimeId,
+        agentId: plan.expected.agentId,
+        deploymentHash: plan.deploymentHash,
+        ambiguousAction: '',
+        receiptId: '',
+        receiptPath: '',
+        calls: [],
+        failures: [],
+        updatedAt: new Date().toISOString(),
+    };
+}
+function persistOperation(root, operation) {
+    assertReportRedacted(operation);
+    atomicJson(safeProjectPath(root, operationRelativePath(operation.workspace, operation.operationId), false), operation);
+}
+function loadOperationAndReceipt(root, name, operationId = '') {
+    let operationPath = '';
+    let expectedOperationHash = '';
+    let receiptPath = '';
+    let expectedReceiptHash = '';
+    let expectedOperationId = '';
+    let expectedReceiptId = '';
+    const requestedOperationId = operationId ? resourceId(operationId, 'operation-id') : '';
+    const pointerPath = safeProjectPath(root, requestedOperationId
+        ? operationBindingPath(name, requestedOperationId)
+        : latestDeploymentPointer(name), false);
+    if (!existsSync(pointerPath)) {
+        if (requestedOperationId)
+            throw new Error('Multica deployment operation binding 不存在');
+        return null;
+    }
+    const pointer = readJson(pointerPath, 'Multica deployment pointer');
+    if (pointer.$schema !== 'dingtalk-agent/multica-deployment-pointer@1') {
+        throw new Error('Multica deployment pointer schema 非法');
+    }
+    expectedOperationId = resourceId(pointer.operationId, 'pointer.operationId');
+    expectedReceiptId = resourceId(pointer.receiptId, 'pointer.receiptId');
+    if (requestedOperationId && expectedOperationId !== requestedOperationId) {
+        throw new Error('Multica deployment operation binding ID 不一致');
+    }
+    operationPath = stringField(pointer.operationPath, 'pointer.operationPath');
+    expectedOperationHash = stringField(pointer.operationHash, 'pointer.operationHash');
+    receiptPath = stringField(pointer.receiptPath, 'pointer.receiptPath');
+    expectedReceiptHash = stringField(pointer.receiptHash, 'pointer.receiptHash');
+    const operationFile = safeProjectPath(root, operationPath, true);
+    const operationBytes = readFileSync(operationFile);
+    if (expectedOperationHash && sha256(operationBytes) !== expectedOperationHash) {
+        throw new Error('Multica deployment operation hash 不一致');
+    }
+    const operation = parseOperation(JSON.parse(operationBytes.toString('utf8')));
+    if (operation.workspace !== name || operation.operationId !== expectedOperationId) {
+        throw new Error('Multica deployment operation 绑定不一致');
+    }
+    if (!receiptPath)
+        receiptPath = operation.receiptPath;
+    if (!receiptPath)
+        throw new Error('Multica deployment operation 尚无 Receipt');
+    const receiptFile = safeProjectPath(root, receiptPath, true);
+    const receiptBytes = readFileSync(receiptFile);
+    if (expectedReceiptHash && sha256(receiptBytes) !== expectedReceiptHash) {
+        throw new Error('Multica deployment Receipt hash 不一致');
+    }
+    const receipt = parseReceipt(JSON.parse(receiptBytes.toString('utf8')));
+    if (receipt.operationId !== operation.operationId || receipt.workspace !== name ||
+        receipt.receiptId !== expectedReceiptId || receipt.evidencePath !== receiptPath ||
+        operation.receiptId !== receipt.receiptId || operation.receiptPath !== receiptPath ||
+        operation.planId !== receipt.planId || operation.action !== receipt.action ||
+        operation.profile !== receipt.profile || operation.deploymentHash !== receipt.deploymentHash) {
+        throw new Error('Multica deployment Receipt 绑定不一致');
+    }
+    assertReportRedacted({ operation, receipt });
+    return { operation, receipt };
+}
+function loadLatestReceipt(root, name) {
+    // A missing pointer means this is the first deployment. Once a pointer exists,
+    // any integrity or binding failure is evidence corruption and must fail closed.
+    return loadOperationAndReceipt(root, name)?.receipt || null;
+}
+function parseOperation(value) {
+    const item = objectValue(value, 'Multica deployment operation');
+    if (item.$schema !== 'dingtalk-agent/multica-deployment-operation@1') {
+        throw new Error('Multica deployment operation schema 非法');
+    }
+    return item;
+}
+function parseReceipt(value) {
+    const item = objectValue(value, 'Multica deployment Receipt');
+    if (item.$schema !== MULTICA_DEPLOYMENT_SCHEMA) {
+        throw new Error('Multica deployment Receipt schema 非法');
+    }
+    return item;
+}
+function runProvider(command, argv, id, kind, cwd, env, timeoutMs, calls) {
+    const budget = deploymentWriteBudgets.get(calls);
+    if (kind === 'write' && budget && calls.filter((call) => call.kind === 'write').length >= budget.forward) {
+        throw new DeploymentFailure('budget.forward-exhausted');
+    }
+    if (kind === 'rollback' && budget && calls.filter((call) => call.kind === 'rollback').length >= budget.rollback) {
+        throw new DeploymentFailure('budget.rollback-exhausted');
+    }
+    const run = spawnSync(command, argv, {
+        cwd, env, encoding: 'utf8', timeout: timeoutMs,
+        maxBuffer: 32 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const stdout = String(run.stdout || '');
+    const stderr = String(run.stderr || '');
+    const exitCode = typeof run.status === 'number' ? run.status : 1;
+    const ambiguous = Boolean(run.error && run.error.code === 'ETIMEDOUT');
+    const passed = !run.error && exitCode === 0;
+    calls.push({
+        id, kind, argv: redactArgv(argv), exitCode,
+        stdoutHash: sha256(stdout), stderrHash: sha256(stderr), passed, ambiguous,
+    });
+    if (!passed)
+        throw new DeploymentFailure(`command.${id}`, ambiguous);
+    return { stdout, stderr };
+}
+function scopedArgs(plan, args) {
+    return ['--profile', plan.profile, '--workspace-id', plan.expected.workspaceId, ...args];
+}
+function redactArgv(argv) {
+    const redactNext = new Set([
+        '--instructions', '--description', '--title', '--content', '--content-file',
+        '--custom-env', '--mcp-config',
+    ]);
+    const result = [];
+    let redact = false;
+    for (const arg of argv) {
+        if (redact) {
+            result.push(`[redacted:${sha256(arg).slice(0, 12)}]`);
+            redact = false;
+            continue;
+        }
+        result.push(arg);
+        if (redactNext.has(arg))
+            redact = true;
+    }
+    return result;
+}
+function parseRemoteSkill(value) {
+    const id = resourceId(value.id, 'remote skill.id');
+    const name = stringField(value.name, 'remote skill.name');
+    const content = optionalString(value.content);
+    const rawFiles = Array.isArray(value.files) ? value.files : [];
+    if (rawFiles.length > MAX_SKILL_SUPPORTING_FILES) {
+        throw new Error(`远端 Skill supporting files 超过 ${MAX_SKILL_SUPPORTING_FILES} 个`);
+    }
+    const files = rawFiles.map((raw, index) => {
+        const item = objectValue(raw, `remote skill.files[${index}]`);
+        const fileContent = optionalString(item.content);
+        const path = safeSkillPath(stringField(item.path, `remote skill.files[${index}].path`));
+        return {
+            id: resourceId(item.id, `remote skill.files[${index}].id`),
+            path, content: fileContent, hash: sha256(fileContent),
+        };
+    }).sort((a, b) => a.path.localeCompare(b.path));
+    const hash = skillTreeHash(content, files.map((item) => ({ path: item.path, hash: item.hash })));
+    return { id, name, content, files, hash };
+}
+function parseRemoteAgent(value) {
+    return {
+        id: resourceId(value.id, 'remote agent.id'),
+        name: stringField(value.name, 'remote agent.name'),
+        runtimeId: resourceId(value.runtime_id, 'remote agent.runtime_id'),
+        instructions: optionalString(value.instructions),
+        status: optionalString(value.status),
+        archived: Boolean(optionalString(value.archived_at)) || value.archived === true,
+    };
+}
+function remoteMatchesDesired(snapshot, source, runtimeId) {
+    if (!snapshot.agent || snapshot.agent.archived || snapshot.agent.runtimeId !== runtimeId ||
+        snapshot.agent.instructions !== source.instructions)
+        return false;
+    const ids = [];
+    for (const local of source.skills) {
+        const remote = snapshot.skills.get(local.name);
+        if (!remote || remote.hash !== local.hash)
+            return false;
+        ids.push(remote.id);
+    }
+    return stableStringify(ids.sort()) === stableStringify([...snapshot.assignedIds].sort());
+}
+function deploymentObservedHash(snapshot, inspectionId) {
+    return digest(stableStringify({
+        inspectionId,
+        agent: snapshot.agent ? {
+            id: snapshot.agent.id,
+            runtimeId: snapshot.agent.runtimeId,
+            instructionsHash: sha256(snapshot.agent.instructions),
+            archived: snapshot.agent.archived,
+        } : null,
+        skills: [...snapshot.skills.entries()].map(([name, skill]) => ({
+            name, id: skill?.id || '', hash: skill?.hash || '',
+        })).sort((a, b) => a.name.localeCompare(b.name)),
+        assignments: [...snapshot.assignedIds].sort(),
+    }));
+}
+function skillTreeHash(content, files) {
+    return digest(stableStringify({
+        main: sha256(content),
+        files: [...files].sort((a, b) => a.path.localeCompare(b.path)),
+    }));
+}
+function frontmatterName(content) {
+    const block = content.match(/^---\s*\n([\s\S]*?)\n---(?:\s*\n|$)/);
+    if (!block)
+        return '';
+    const match = block[1].match(/^name:\s*["']?([^"'\n]+?)["']?\s*$/m);
+    return match ? match[1].trim() : '';
+}
+function rejectCredentialMaterial(content, label) {
+    const patterns = [
+        /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/,
+        /\bBearer\s+[A-Za-z0-9._~+\/-]{20,}/i,
+        /\b(?:sk|pat|token)[-_][A-Za-z0-9_-]{24,}\b/i,
+        /(?:access[_-]?token|client[_-]?secret|password)\s*[:=]\s*["']?(?!<|\*|replace|example|redacted)[A-Za-z0-9._~+\/-]{16,}/i,
+    ];
+    if (patterns.some((pattern) => pattern.test(content))) {
+        throw new Error(`${label} 检测到疑似真实凭据，拒绝部署`);
+    }
+}
+function assertReportRedacted(value) {
+    const source = JSON.stringify(value);
+    if (/-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|\bBearer\s+[A-Za-z0-9._~+\/-]{20,}|\b(?:sk|pat|token)[-_][A-Za-z0-9_-]{24,}\b/i.test(source)) {
+        throw new Error('Multica deployment evidence 脱敏失败');
+    }
+    if (/"(?:instructions|content|stdout|stderr|email|serverUrl|server_url)"\s*:/i.test(source)) {
+        throw new Error('Multica deployment evidence 包含禁止的原始内容字段');
+    }
+}
+function emptySmoke(status, requiredSkills) {
+    return {
+        status, marker: '', markerHash: '', issueId: '', taskId: '', taskStatus: '',
+        requiredSkills: [...requiredSkills].sort(), loadedSkills: [],
+        toolTracePassed: false, responsePassed: false, responseHash: '', failures: [],
+    };
+}
+function emptyRollback(attempted) {
+    return { attempted, passed: !attempted, actions: [], failures: [] };
+}
+function writeTemporaryContent(root, name, content) {
+    const path = join(root, `${safeFileName(name)}.txt`);
+    writeFileSync(path, content, { mode: 0o600 });
+    return path;
+}
+function safeFileName(value) {
+    return value.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 120);
+}
+function readUtf8(path, label, limit) {
+    const bytes = readFileSync(path);
+    if (bytes.length > limit)
+        throw new Error(`${label} 超过 ${limit} bytes`);
+    if (bytes.includes(0))
+        throw new Error(`${label} 不是 UTF-8 文本`);
+    const content = bytes.toString('utf8');
+    if (Buffer.from(content, 'utf8').compare(bytes) !== 0)
+        throw new Error(`${label} 不是合法 UTF-8`);
+    return content;
+}
+function readJson(path, label) {
+    if (lstatSync(path).isSymbolicLink())
+        throw new Error(`${label} 不能是符号链接`);
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new Error(`${label} 不是合法 JSON`);
+    }
+}
+function jsonObject(value, label) {
+    let parsed = value;
+    if (typeof value === 'string') {
+        try {
+            parsed = JSON.parse(value);
+        }
+        catch {
+            throw new DeploymentFailure(`json.${label}`);
+        }
+    }
+    return objectValue(parsed, label);
+}
+function jsonArray(value, label) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new DeploymentFailure(`json.${label}`);
+    }
+    if (!Array.isArray(parsed) || parsed.some((item) => !item || typeof item !== 'object' || Array.isArray(item))) {
+        throw new DeploymentFailure(`shape.${label}`);
+    }
+    return parsed;
+}
+function objectValue(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${label} 必须是 object`);
+    }
+    return value;
+}
+function stringField(value, label) {
+    if (typeof value !== 'string' || !value)
+        throw new Error(`${label} 必须是非空字符串`);
+    return value;
+}
+function optionalString(value) {
+    return typeof value === 'string' ? value : '';
+}
+function resourceId(value, label) {
+    const item = stringField(value, label);
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{1,127}$/.test(item) ||
+        /^(?:sk-|bearer|token[-_])/i.test(item)) {
+        throw new Error(`${label} 不是安全稳定 ID`);
+    }
+    return item;
+}
+function safeSkillPath(value) {
+    if (!value || value === 'SKILL.md' || value.startsWith('/') || value.includes('\\') ||
+        value.split('/').some((part) => !part || part === '.' || part === '..')) {
+        throw new Error(`远端 Skill supporting file 路径非法: ${value}`);
+    }
+    return value;
+}
+function requireMulticaWorkspace(start, name, cliVersion = '') {
+    const workspace = showDevelopmentWorkspace(start, name, cliVersion);
+    if (workspace.provider.kind !== 'multica' || workspace.legacy) {
+        throw new Error(`Workspace ${name} 不是 multica Provider；deploy 不执行 ${workspace.provider.kind}`);
+    }
+    return workspace;
+}
+function safeExternalSkillRoot(path) {
+    if (!existsSync(path) || lstatSync(path).isSymbolicLink()) {
+        throw new Error(`Canonical Multica Boot Skill 不存在或是符号链接: ${path}`);
+    }
+    return realpathSync(path);
+}
+function safeProjectPath(root, ref, mustExist) {
+    const rootReal = realpathSync(resolve(root));
+    const candidate = resolve(rootReal, ref);
+    const rel = relative(rootReal, candidate);
+    if (!isInside(rootReal, candidate))
+        throw new Error(`Multica deployment 路径越出 Project: ${ref}`);
+    if (mustExist && !existsSync(candidate))
+        throw new Error(`Multica deployment 路径不存在: ${ref}`);
+    if (existsSync(candidate)) {
+        if (lstatSync(candidate).isSymbolicLink())
+            throw new Error(`Multica deployment 路径不能是符号链接: ${ref}`);
+        if (!isInside(rootReal, realpathSync(candidate)))
+            throw new Error(`Multica deployment 真实路径越界: ${ref}`);
+    }
+    let ancestor = dirname(candidate);
+    while (!existsSync(ancestor)) {
+        const parent = dirname(ancestor);
+        if (parent === ancestor)
+            break;
+        ancestor = parent;
+    }
+    if (!existsSync(ancestor) || !isInside(rootReal, realpathSync(ancestor))) {
+        throw new Error(`Multica deployment 父目录真实路径越界: ${ref}`);
+    }
+    void rel;
+    return candidate;
+}
+function isInside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`));
+}
+function deploymentsRoot(name) {
+    return join(MULTICA_EVIDENCE_ROOT, safeName(name), 'multica-deployments');
+}
+function receiptsRoot(name) {
+    return join(deploymentsRoot(name), 'receipts');
+}
+function receiptRelativePath(name, receiptId) {
+    return join(receiptsRoot(name), `${resourceId(receiptId, 'receipt-id')}.json`);
+}
+function operationRelativePath(name, operationId) {
+    return join(deploymentsRoot(name), 'operations', `${resourceId(operationId, 'operation-id')}.json`);
+}
+function latestDeploymentPointer(name) {
+    return join(deploymentsRoot(name), 'latest.json');
+}
+function operationBindingPath(name, operationId) {
+    return join(deploymentsRoot(name), 'bindings', `${resourceId(operationId, 'operation-id')}.json`);
+}
+function safeName(value) {
+    if (!/^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/.test(value)) {
+        throw new Error(`Workspace name 非法: ${value}`);
+    }
+    return value;
+}
+function positiveTimeout(value, fallback, max) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value < 100 || value > max) {
+        throw new Error(`Multica timeout 必须在 100..${max} ms`);
+    }
+    return Math.floor(value);
+}
+function atomicJson(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.tmp-${process.pid}-${randomUUID().slice(0, 8)}`;
+    const source = `${JSON.stringify(value, null, 2)}\n`;
+    writeFileSync(temp, source, { mode: 0o600, flag: 'wx' });
+    renameSync(temp, path);
+    if (readFileSync(path, 'utf8') !== source)
+        throw new Error(`原子写后回读不一致: ${path}`);
+}
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+//# sourceMappingURL=multica-deploy.js.map