@playcraft/cli 0.1.54 → 0.1.55-beta

package/dist/workspace-runtime/workspaces/parameter-agent-inputs.js

@@ -0,0 +1,97 @@
+import { createHash } from 'node:crypto';
+import { lstat, readdir, readFile, realpath } from 'node:fs/promises';
+import { relative, resolve, sep } from 'node:path';
+import { workspaceRelativePathSchema } from '@playcraft/common/cloud-workspace/runtime';
+export const parameterDigest = (content) => createHash('sha256').update(content).digest('hex');
+const skippedDirectories = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.next', '.vite', '.cache', '.playcraft-editor-preview', '.playcraft-delivery', '.playcraft-temp', 'parameter-admission']);
+const snapshotByteLimit = 32 * 1024 * 1024;
+const inputExtension = /\.(?:[cm]?[jt]sx?|json5?|ya?ml|html|css|scss|glsl|wgsl|vert|frag|toml)$/i;
+export class ParameterAgentError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'ParameterAgentError';
+    }
+}
+export function parameterInputPath(path) {
+    if (!workspaceRelativePathSchema.safeParse(path).success)
+        return false;
+    const segments = path.split('/');
+    if (segments.some(segment => skippedDirectories.has(segment)))
+        return false;
+    if (segments.some(segment => segment.startsWith('.') && segment !== '.playcraft'))
+        return false;
+    if (segments[0] === '.playcraft' && path !== '.playcraft/workspace.json')
+        return false;
+    if (segments.some(segment => /(?:secret|credential|private[-_.]?key|\.pem$|\.key$)/i.test(segment)))
+        return false;
+    return inputExtension.test(path);
+}
+export async function readParameterAgentFile(root, path, limit = 2 * 1024 * 1024) {
+    const parsed = workspaceRelativePathSchema.safeParse(path);
+    if (!parsed.success)
+        throw new ParameterAgentError('parameter_agent_path_invalid');
+    const base = await realpath(root);
+    let target = base;
+    const segments = parsed.data.split('/');
+    for (let index = 0; index < segments.length; index++) {
+        target = resolve(target, segments[index]);
+        const stat = await lstat(target);
+        if (stat.isSymbolicLink() || (index < segments.length - 1 ? !stat.isDirectory() : !stat.isFile()))
+            throw new ParameterAgentError('parameter_agent_path_invalid');
+        if (index === segments.length - 1 && stat.size > limit)
+            throw new ParameterAgentError('parameter_agent_input_too_large');
+    }
+    const rel = relative(base, await realpath(target));
+    if (rel === '..' || rel.startsWith(`..${sep}`))
+        throw new ParameterAgentError('parameter_agent_path_invalid');
+    const bytes = await readFile(target);
+    if (bytes.byteLength > limit)
+        throw new ParameterAgentError('parameter_agent_input_too_large');
+    return bytes;
+}
+export async function parameterInputSnapshot(root) {
+    const base = await realpath(root);
+    const sources = [];
+    let total = 0;
+    let directories = 0;
+    const walk = async (path, depth) => {
+        if (depth > 24 || ++directories > 4096)
+            throw new ParameterAgentError('parameter_agent_input_limit');
+        const entries = await readdir(resolve(base, path), { withFileTypes: true });
+        if (entries.length > 4096)
+            throw new ParameterAgentError('parameter_agent_input_limit');
+        for (const entry of entries) {
+            const child = path ? `${path}/${entry.name}` : entry.name;
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                if (skippedDirectories.has(entry.name) || (entry.name.startsWith('.') && entry.name !== '.playcraft'))
+                    continue;
+                if (child.startsWith('.playcraft/'))
+                    continue;
+                await walk(child, depth + 1);
+            }
+            else if (entry.isFile() && parameterInputPath(child)) {
+                if (sources.length >= 2048)
+                    throw new ParameterAgentError('parameter_agent_input_limit');
+                let bytes;
+                try {
+                    // Snapshot hashing shares a total budget; report evidence keeps the reader's default limit.
+                    bytes = await readParameterAgentFile(base, child, snapshotByteLimit - total);
+                }
+                catch (error) {
+                    if (error instanceof ParameterAgentError && error.code === 'parameter_agent_input_too_large')
+                        throw new ParameterAgentError('parameter_agent_input_limit');
+                    throw error;
+                }
+                total += bytes.byteLength;
+                sources.push({ path: child, sha256: parameterDigest(bytes) });
+            }
+        }
+    };
+    await walk('', 0);
+    sources.sort((left, right) => left.path.localeCompare(right.path));
+    return { sources, digest: parameterDigest(JSON.stringify(sources)) };
+}

package/dist/workspace-runtime/workspaces/parameter-agent-protocol.js

@@ -0,0 +1,40 @@
+/** Versioned product protocol reference, compiled into the published CLI (Command Line Interface, 命令行接口). */
+export const PARAMETER_AGENT_PROTOCOL = `PlayCraft parameter integration protocol v1.1
+This is a product configuration reference, not a skill activation. Preserve the current project skill lock and permission/work modes.
+Work only in the current authorized engineering directory. Never edit Remix Editor or a different workspace directory.
+
+Configuration:
+- Reuse existing schema and sparse theme data. .playcraft/workspace.json may declare parameters:{schemaPath,dataPath,themeId}; preserve all unrelated manifest keys. parameters accepts only those three keys.
+- A schema already declares configurable fields. Do not add a parallel xplatform.parameter protocol. Reuse existing field paths and synonymous parameters first.
+- For a new project, create a schema, a sparse data file ({} is valid), matching platform text, and explicit manifest paths. Use gamePlay.preloaded / gamePlay.sections / gamePlay.settlement for the three-screen tree. Preserve existing project paths instead of migrating gratuitously.
+- Object nodes use type:object/properties; leaves declare a supported primitive type and a valid default. Preserve units, known bounds/enum and meaning; do not invent verified limits without code evidence. Basic leaves support string, finite number, integer, boolean and null. Preserve valid standard required arrays without inventing unrelated requiredness. Malformed required declarations and unsupported $ref/conditional composition remain invalid.
+- Missing theme values inherit schema defaults; editing creates a raw override and restoring defaults removes that override. Never flatten resolved values into theme.data. Preserve comments, unknown data and unrelated overrides.
+- Platform labels use i18n.platform.json5 beside the schema, same tree, with _self.title/description text for zh/en. Preserve xplatform.ext.readonly and xplatform.showIf/showIfAny. Resources (xplatform.value_type:path), multilingual references (i18n), arrays and complex structures retain their semantics; do not disguise them as primitive controls.
+
+Consumption and checks:
+- Modify real game consumers and the neutral configuration resolver, shared by production and preview. A schema-only field or a new getter with no real consumer is incomplete.
+- The development preview runtime is separate from advertising code. Do not route debugging through advertising configuration caches. Production must not depend on the preview runtime.
+- For an add/admit integration that needs instant preview, obtain the supported development SDK (Software Development Kit, 软件开发工具包) with playcraft preview-runtime init --dir . in this engineering directory. It copies versioned modules/types/helpers to .playcraft/preview-runtime without changing game entries; refuse to overwrite modified managed files. Discovery remains read-only and must not run initialization.
+- Read .playcraft/preview-runtime/README.md. Create a separate preview entry importing connectPreviewRuntime/readWorkspacePreviewContext from its relative runtime.mjs; adapt the real resolver/store/game callbacks and explicitly register consumed fields. Add a build:cloud-preview script invoking node .playcraft/preview-runtime/build-preview.mjs --entry <relative-preview-entry> with optional --config <project-vite-preview-config> and --mount-id <container>. The project needs a compatible development Vite; legacy webpack/playable-scripts projects require explicit preview plugins/aliases/constants, not a production build migration.
+- Preserve unrelated .playcraft/workspace.json keys and declare previewRuntime:{version:1,buildScript:"build:cloud-preview",outputPath:".playcraft-editor-preview/index.html",reportPath:".playcraft-editor-preview/report.json",configContractVersion:"<actual-contract-version>",entryPath:"<actual-preview-entry>",viteConfigPath:"<preview-build-config>",mountId:"game",gameFilePaths:["<actual-preview-entry>","<real-resolver>","<real-consumer>","<preview-build-config>",".playcraft/preview-runtime/runtime.mjs",".playcraft/preview-runtime/build-preview.mjs"]}. List actual existing input paths rather than these placeholders; omit viteConfigPath when no custom configuration is needed. For the copied SDK, entryPath is required and the platform directly invokes its trusted packaged helper with the declared entry/config/mount arguments; the project buildScript is not executed for admission and cannot self-author its module evidence. Managed SDK files belong to the separate preview module report, not parameter-admission origin/consumer evidence. The platform supplies PLAYCRAFT_RUNTIME_PREVIEW_CONTEXT and verifies the helper's independent SDK/module report; do not fabricate context or a successful live report.
+- Keep production independent. Vite production builds may import previewRuntimeReleaseGuard from .playcraft/preview-runtime/release-guard.mjs and register it with root and actual previewEntries. Other builders need equivalent real module-graph evidence. If preview adaptation, a production boundary or a dependency is unavailable, report the concrete missing work instead of claiming isolation.
+- Instant capability requires real field registration and a version-matched preview handshake. Reports cannot declare live capability. A newly integrated field may require one preview build first.
+- Add or extend package.json script test:parameters with meaningful tests of schema/default/sparse overrides and real consumer behavior; changing the requested value must affect its consumer. Preserve an existing test script. Ensure the production build script build exists and succeeds. Optional typecheck is also run by the platform.
+- The platform independently runs only pnpm run test:parameters, pnpm run build, and optional pnpm run typecheck. Reports cannot choose executable commands. Do not replace checks with successful echo statements or self-reported flags.
+- Do not claim a complete production module isolation proof without a trustworthy module report. Passing build/checks proves only their stated coverage.
+
+Report JSON (JavaScript Object Notation, JavaScript 对象表示法) contract (no second copy of parameter values):
+{version:1,taskId:"<exact platform task id>",sources:[{path:"relative/input.ts",sha256:"<current raw-file digest>"}],candidates:[{id:"stable-id",title:"User-facing title",description:"Optional purpose",fieldPath:["gamePlay","sections","board","speed"],origins:[{path:"relative/input.ts",line:1,summary:"Actual origin evidence"}],consumers:[{path:"src/game.ts",line:1,summary:"Actual production consumer and behavior"}],status:"candidate",missing:["Concrete incomplete steps"]}]}
+- Candidate status is exactly candidate, implemented, or blocked. Completed integration candidates use implemented with an empty missing array; discovery keeps candidates unimplemented.
+- Include current raw-file SHA-256 (Secure Hash Algorithm 256-bit, 256位安全散列算法) digests for every origin and consumer. Include relevant schema/data/platform labels/workspace manifest/check scripts/package files only when they pass the eligible input path filter below. Package lock evidence is limited to eligible package locks such as pnpm-lock.yaml and package-lock.json; a general skill lock or other metadata lock is not package evidence.
+- sources must use only platform-snapshot input paths: engineering-relative regular files with no symlink parents, no absolute paths, backslashes, colon, empty segments, . or .. segments; paths are at most 512 characters. Eligible suffixes are [cm]?[jt]sx? (JavaScript/TypeScript and their c/m variants), json, json5, yaml, yml, html, css, scss, glsl, wgsl, vert, frag and toml, case-insensitive.
+- Skip these directories anywhere in a path: node_modules, .git, dist, build, coverage, .next, .vite, .cache, .playcraft-editor-preview, .playcraft-delivery, .playcraft-temp and parameter-admission. Hidden path segments are excluded except the workspace manifest rule: .playcraft/workspace.json is the only .playcraft evidence input. Exclude any segment containing secret, credential, private[-_.]?key, or ending in .pem or .key, case-insensitive. Do not read credentials, dependency trees or build outputs as evidence.
+- AGENTS.md, SKILL.md (including SKILL/SKILL.md), .playcraft/skills.lock.json, other Markdown instructions and managed .playcraft/preview-runtime files must not appear in sources, origins or consumers. Reading workspace instructions does not make them eligible evidence inputs. Keep those documents as working instructions, not report sources.
+- Eligible source snapshots remain bounded by 33,554,432 total bytes, 2048 files, 4096 directories, 4096 entries per directory and depth 24. The platform may hash a large eligible source within that total budget, but an individual origin/consumer evidence file must fit the 2,097,152-byte read limit. Choose the actual small production consumer instead of citing a large vendor bundle.
+- Discovery writes only its exact development report: do not alter schema/data to make discovery or validation pass, and do not claim an integration or successful checks. The platform derives the complete catalog from the existing schema. Do not copy every existing schema field into the discovery report. The first discovery batch must contain at most 12 distinct, valuable candidates, prioritizing missing meaningful controls or concrete integration gaps; do not manufacture duplicates or filler. Explain additional discovery work in the final response rather than expanding this report into a catalog.
+- Keep the complete report at most 1,048,576 bytes encoded as UTF-8 (Unicode Transformation Format 8-bit, 8位Unicode转换格式). The strict structure accepts only the shown keys: 1..2048 unique sources with unique paths and 64-character lowercase hexadecimal digests; 0..128 candidates with unique ids (discovery is further limited to the first 12).
+- Each candidate id is 1..128 characters matching [A-Za-z0-9][A-Za-z0-9._-]*, title 1..256, optional description at most 4000; origins 1..32, consumers 0..32, missing 0..32 strings of 1..1000 characters. Each evidence summary is 1..2000 characters; an optional line is a positive integer no greater than 1,000,000 and must exist in the current file. A fieldPath, when present, contains 1..16 identifier segments of 1..128 characters, excluding __proto__, prototype and constructor. Every origin/consumer path must have its current digest declared in sources.
+- Summaries and source snippets are evidence claims, not proof of semantics. The platform checks current files, declared defaults, write support, and independently executed check exits.
+- No passed/ready/live/checks fields are accepted in the report. All implementation and validation statements remain claims until platform verification.
+- If blocked or partial, preserve reviewable changes and list concrete missing work. Do not overwrite later user edits or claim multi-file changes were atomic.
+`;

package/dist/workspace-runtime/workspaces/parameter-agent-store.js

@@ -0,0 +1,58 @@
+import { mkdir, readFile, readdir, rename, lstat, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { parameterAgentTaskRecordSchema, parameterAgentTaskRequestSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { ParameterAgentError, parameterDigest } from './parameter-agent-inputs.js';
+export function parameterTaskWorkspace(state, workspaceId) {
+    if (!workspaceId && state.config.workspaceMode === 'multi')
+        throw new ParameterAgentError('parameter_agent_scope_invalid');
+    return workspaceId ?? 'local';
+}
+async function taskDirectory(state, workspaceId, directoryName, root) {
+    const parent = resolve(state.config.stateDir, 'parameter-agent');
+    if (root) {
+        const rel = relative(resolve(root), parent);
+        if (rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)))
+            throw new ParameterAgentError('parameter_agent_state_not_private');
+    }
+    const scope = [state.config.environment, state.config.userId, state.config.runtimeId, workspaceId, directoryName];
+    const directory = join(parent, parameterDigest(JSON.stringify(scope)));
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    if ((await lstat(parent)).isSymbolicLink() || (await lstat(directory)).isSymbolicLink())
+        throw new ParameterAgentError('parameter_agent_state_invalid');
+    return directory;
+}
+export async function readPrivateParameterTask(state, workspaceId, directoryName, taskId, root) {
+    if (!/^[a-f0-9-]{36}$/i.test(taskId))
+        throw new ParameterAgentError('parameter_agent_task_invalid');
+    const file = join(await taskDirectory(state, workspaceId, directoryName, root), `${taskId}.json`);
+    try {
+        const stat = await lstat(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
+            throw new ParameterAgentError('parameter_agent_state_invalid');
+        const value = JSON.parse(await readFile(file, 'utf8'));
+        value.record = parameterAgentTaskRecordSchema.parse(value.record);
+        value.request = parameterAgentTaskRequestSchema.parse(value.request);
+        if (value.record.taskId !== taskId || value.request.taskId !== taskId || value.record.workspaceId !== workspaceId || value.record.directoryName !== directoryName || !/^[a-f0-9]{64}$/.test(value.initialDigest))
+            throw new ParameterAgentError('parameter_agent_state_invalid');
+        return value;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+export async function writePrivateParameterTask(state, task, root) {
+    const directory = await taskDirectory(state, task.record.workspaceId, task.record.directoryName, root);
+    const record = parameterAgentTaskRecordSchema.parse(task.record);
+    const temporary = join(directory, `.${record.taskId}.${randomUUID()}.tmp`);
+    await writeFile(temporary, JSON.stringify({ ...task, record }), { mode: 0o600 });
+    await rename(temporary, join(directory, `${record.taskId}.json`));
+}
+export async function listPrivateParameterTaskIds(state, workspaceId, directoryName, root) {
+    const names = (await readdir(await taskDirectory(state, workspaceId, directoryName, root))).filter(name => /^[a-f0-9-]{36}\.json$/i.test(name));
+    if (names.length > 256)
+        throw new ParameterAgentError('parameter_agent_task_limit');
+    return names.map(name => name.slice(0, -5));
+}

package/dist/workspace-runtime/workspaces/parameter-agent.js

@@ -0,0 +1,284 @@
+import { randomUUID } from 'node:crypto';
+import { parameterAgentReportSchema, parameterAgentTaskRequestSchema, parameterAgentVerifyPayloadSchema, parameterCatalog, stableStringify, validateParameterChange, } from '@playcraft/common/cloud-workspace/runtime';
+import { readWorkspaceParameters } from './parameters.js';
+import { revisionScope } from './registry.js';
+import { runDeveloperCommand } from './developer-command.js';
+import { PARAMETER_AGENT_PROTOCOL } from './parameter-agent-protocol.js';
+import { ParameterAgentError, parameterDigest, parameterInputSnapshot, readParameterAgentFile } from './parameter-agent-inputs.js';
+import { listPrivateParameterTaskIds, parameterTaskWorkspace, readPrivateParameterTask, writePrivateParameterTask } from './parameter-agent-store.js';
+export { ParameterAgentError } from './parameter-agent-inputs.js';
+const reportPath = (taskId) => `.playcraft/parameter-admission/${taskId}.json`;
+const now = () => new Date().toISOString();
+function scope(state, operation, requireSession = true) {
+    const workspaceId = parameterTaskWorkspace(state, operation.workspaceId);
+    const directoryName = operation.directoryName ?? 'basic';
+    if ((requireSession && !operation.sessionId) || directoryName === 'root' || !/^(basic|remix-[a-z0-9][a-z0-9-]{3,63})$/.test(directoryName))
+        throw new ParameterAgentError('parameter_agent_scope_invalid');
+    if (operation.environment !== state.config.environment || operation.userId !== state.config.userId
+        || (operation.generation !== undefined && operation.generation !== state.config.generation)
+        || (operation.runtimeEpoch !== undefined && operation.runtimeEpoch !== state.runtimeEpoch))
+        throw new ParameterAgentError('parameter_agent_scope_expired');
+    return { workspaceId, directoryName, sessionId: operation.sessionId ?? '' };
+}
+function current(state, task) {
+    return task.record.generation === state.config.generation && task.record.runtimeEpoch === state.runtimeEpoch;
+}
+async function update(state, task, patch, root) {
+    task.record = { ...task.record, ...patch, updatedAt: now() };
+    await writePrivateParameterTask(state, task, root);
+    return task.record;
+}
+async function inspectReport(root, task, snapshot) {
+    const bytes = await readParameterAgentFile(root, task.record.reportPath, 1024 * 1024);
+    let report;
+    try {
+        report = parameterAgentReportSchema.parse(JSON.parse(bytes.toString('utf8')));
+    }
+    catch {
+        throw new ParameterAgentError('parameter_agent_report_invalid');
+    }
+    if (report.taskId !== task.record.taskId)
+        throw new ParameterAgentError('parameter_agent_report_task_mismatch');
+    const inputs = new Map(snapshot.sources.map(source => [source.path, source.sha256]));
+    const declared = new Map(report.sources.map(source => [source.path, source.sha256]));
+    for (const source of report.sources) {
+        if (!inputs.has(source.path))
+            throw new ParameterAgentError('parameter_agent_evidence_invalid');
+        if (inputs.get(source.path) !== source.sha256)
+            throw new ParameterAgentError('parameter_agent_report_stale');
+    }
+    for (const candidate of report.candidates) {
+        for (const evidence of [...candidate.origins, ...candidate.consumers]) {
+            if (!declared.has(evidence.path))
+                throw new ParameterAgentError('parameter_agent_evidence_missing');
+            const content = await readParameterAgentFile(root, evidence.path);
+            if (!content.toString('utf8').trim() || (evidence.line && evidence.line > content.toString('utf8').split('\n').length))
+                throw new ParameterAgentError('parameter_agent_evidence_invalid');
+        }
+    }
+    return report;
+}
+export async function prepareParameterAgentTask(state, operation, value, root) {
+    const request = parameterAgentTaskRequestSchema.parse(value);
+    if (operation.kind !== 'session.turn' || operation.clientRequestId !== request.taskId)
+        throw new ParameterAgentError('parameter_agent_task_identity_invalid');
+    const owner = scope(state, operation);
+    const existing = await readPrivateParameterTask(state, owner.workspaceId, owner.directoryName, request.taskId, root);
+    if (existing && (existing.record.sessionId !== owner.sessionId || !current(state, existing) || stableStringify(existing.request) !== stableStringify(request)))
+        throw new ParameterAgentError('parameter_agent_task_conflict');
+    const document = await readWorkspaceParameters(root, state.journal.fileRevisions(revisionScope(state, operation.workspaceId, owner.directoryName)));
+    if (request.sourceFingerprint && request.sourceFingerprint !== document.sourceFingerprint)
+        throw new ParameterAgentError('parameter_source_conflict');
+    let selected;
+    if (request.candidate) {
+        const parent = await readPrivateParameterTask(state, owner.workspaceId, owner.directoryName, request.candidate.taskId, root);
+        if (!parent || !current(state, parent) || ['running', 'uncertain', 'interrupted'].includes(parent.record.status))
+            throw new ParameterAgentError('parameter_agent_candidate_unavailable');
+        const snapshot = await parameterInputSnapshot(root);
+        const report = await inspectReport(root, parent, snapshot);
+        selected = report.candidates.find(candidate => candidate.id === request.candidate.candidateId);
+        if (!selected || !parent.record.sourceDigest || parent.record.sourceDigest !== snapshot.digest)
+            throw new ParameterAgentError('parameter_agent_candidate_stale');
+    }
+    const initial = await parameterInputSnapshot(root);
+    const timestamp = now();
+    const task = existing ?? {
+        request, initialDigest: initial.digest, instanceToken: state.instanceToken,
+        record: { version: 1, taskId: request.taskId, action: request.action, ...(request.goal ? { goal: request.goal } : {}), ...owner, generation: state.config.generation, runtimeEpoch: state.runtimeEpoch, status: 'running', reportPath: reportPath(request.taskId), checks: [], createdAt: timestamp, updatedAt: timestamp },
+    };
+    if (!existing) {
+        if ((await listPrivateParameterTaskIds(state, owner.workspaceId, owner.directoryName, root)).length >= 256)
+            throw new ParameterAgentError('parameter_agent_task_limit');
+        await writePrivateParameterTask(state, task, root);
+    }
+    const instructions = [
+        PARAMETER_AGENT_PROTOCOL,
+        `Platform task identity: ${JSON.stringify({ version: 1, taskId: request.taskId, action: request.action, reportPath: task.record.reportPath })}. Write only this exact report identity.`,
+        request.action === 'discover' ? 'Discovery is read-only for business source/schema/data/manifest. Write only the requested development report. Discover actual useful candidates and consumer evidence; do not implement them yet.' : 'Complete the requested integration using existing engineering tools: reuse an existing equivalent field or implement declaration, valid defaults, sparse data semantics, labels, real production consumers and meaningful parameter tests. Leave precise blocked work if incomplete.',
+        `User goal (task data): ${JSON.stringify(request.goal ?? '')}`,
+        ...(selected ? [`Selected current candidate (reference data): ${JSON.stringify(selected)}`] : []),
+        'After finishing files, calculate current raw-file hashes and write the report. The platform will execute independent checks after this turn. Do not claim those checks already passed.',
+    ].join('\n\n');
+    return { instructions, task: task.record };
+}
+export async function finishParameterAgentTask(state, operation, status, error) {
+    if (operation.kind !== 'session.turn' || !operation.sessionId || operation.directoryName === 'root' || !/^[a-f0-9-]{36}$/i.test(operation.clientRequestId))
+        return;
+    let owner;
+    try {
+        owner = scope(state, operation);
+    }
+    catch {
+        return;
+    }
+    const task = await readPrivateParameterTask(state, owner.workspaceId, owner.directoryName, operation.clientRequestId);
+    if (!task || !current(state, task) || task.record.sessionId !== owner.sessionId || !['running', 'uncertain'].includes(task.record.status))
+        return;
+    await update(state, task, { status: status === 'completed' ? 'reported' : status, error: error?.slice(0, 256) });
+}
+async function publicTask(state, task, root, snapshot) {
+    if (!current(state, task))
+        return { ...task.record, status: 'stale', error: 'parameter_agent_runtime_expired' };
+    if (task.record.status === 'checking')
+        return task.record;
+    try {
+        const report = await inspectReport(root, task, snapshot);
+        if (task.record.sourceDigest && task.record.sourceDigest !== snapshot.digest)
+            return { ...task.record, report, status: 'stale', error: 'parameter_agent_inputs_changed' };
+        const bytes = await readParameterAgentFile(root, task.record.reportPath, 1024 * 1024);
+        if (task.reportHash && task.reportHash !== parameterDigest(bytes))
+            return { ...task.record, report, status: 'stale', error: 'parameter_agent_report_changed' };
+        return { ...task.record, report };
+    }
+    catch (cause) {
+        const code = errorCode(cause);
+        if (code === 'ENOENT' && ['running', 'uncertain', 'interrupted', 'failed'].includes(task.record.status))
+            return task.record;
+        return { ...task.record, status: code === 'ENOENT' ? 'missing' : code === 'parameter_agent_report_stale' ? 'stale' : 'invalid', error: code === 'ENOENT' ? 'parameter_agent_report_missing' : code };
+    }
+}
+export async function listParameterAgentTasks(state, workspaceId, directoryName, root) {
+    if (directoryName === 'root')
+        return [];
+    const workspace = parameterTaskWorkspace(state, workspaceId);
+    const ids = await listPrivateParameterTaskIds(state, workspace, directoryName, root);
+    if (!ids.length)
+        return [];
+    const snapshot = await parameterInputSnapshot(root);
+    const tasks = [];
+    for (const id of ids) {
+        let task = await readPrivateParameterTask(state, workspace, directoryName, id, root);
+        if (task && ['running', 'uncertain'].includes(task.record.status) && current(state, task)) {
+            const operation = state.journal.listOperations?.().map(item => item.operation).find(item => item.kind === 'session.turn'
+                && item.clientRequestId === id && item.sessionId === task.record.sessionId
+                && parameterTaskWorkspace(state, item.workspaceId) === workspace && (item.directoryName ?? 'basic') === directoryName);
+            if (operation && ['completed', 'failed', 'interrupted', 'uncertain'].includes(operation.status)) {
+                await finishParameterAgentTask(state, operation, operation.status, operation.error);
+                task = await readPrivateParameterTask(state, workspace, directoryName, id, root);
+            }
+        }
+        if (task && current(state, task) && task.instanceToken !== state.instanceToken) {
+            if (task.record.status === 'checking') {
+                await update(state, task, { status: 'needs-verification', receiptId: undefined, error: 'parameter_agent_check_interrupted' }, root);
+            }
+            else if (task.record.status === 'running') {
+                await update(state, task, { status: 'uncertain', receiptId: undefined, error: 'parameter_agent_turn_unconfirmed_after_restart' }, root);
+            }
+        }
+        if (task)
+            tasks.push(await publicTask(state, task, root, snapshot));
+    }
+    return tasks.sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+}
+function errorCode(cause) {
+    return cause instanceof Error && 'code' in cause && typeof cause.code === 'string' ? cause.code : 'parameter_agent_verification_failed';
+}
+export async function verifyParameterAgentTask(state, operation, payload, root, options = {}) {
+    if (operation.kind !== 'parameter.verify')
+        throw new ParameterAgentError('parameter_agent_task_identity_invalid');
+    const owner = scope(state, operation, false);
+    const { taskId } = parameterAgentVerifyPayloadSchema.parse(payload);
+    const task = await readPrivateParameterTask(state, owner.workspaceId, owner.directoryName, taskId, root);
+    if (!task)
+        throw new ParameterAgentError('parameter_agent_task_unknown');
+    const instanceToken = state.instanceToken;
+    const assertActive = () => {
+        options.signal?.throwIfAborted();
+        options.assertActive?.();
+        if (!current(state, task) || state.journal.destroyed() || instanceToken !== state.instanceToken)
+            throw new ParameterAgentError('parameter_agent_scope_expired');
+    };
+    assertActive();
+    if (['running', 'uncertain', 'interrupted'].includes(task.record.status))
+        throw new ParameterAgentError('parameter_agent_turn_not_completed');
+    try {
+        const before = await parameterInputSnapshot(root);
+        const report = await inspectReport(root, task, before);
+        task.record.report = report;
+        task.reportHash = parameterDigest(await readParameterAgentFile(root, task.record.reportPath, 1024 * 1024));
+        if (task.request.action === 'discover') {
+            if (task.initialDigest !== before.digest)
+                throw new ParameterAgentError('parameter_agent_discovery_modified_sources');
+            assertActive();
+            if ((await parameterInputSnapshot(root)).digest !== before.digest || parameterDigest(await readParameterAgentFile(root, task.record.reportPath, 1024 * 1024)) !== task.reportHash)
+                throw new ParameterAgentError('parameter_agent_inputs_changed');
+            return update(state, task, { status: 'candidates', sourceDigest: before.digest, checks: [], error: undefined, receiptId: undefined }, root);
+        }
+        const document = await readWorkspaceParameters(root, state.journal.fileRevisions(revisionScope(state, operation.workspaceId, owner.directoryName)));
+        if (document.status !== 'ready')
+            throw new ParameterAgentError('parameter_agent_parameters_not_ready');
+        const catalog = parameterCatalog(document.schema, document.data);
+        const implemented = report.candidates.filter(candidate => candidate.status === 'implemented');
+        if (!implemented.length || report.candidates.some(candidate => candidate.status !== 'implemented' || candidate.missing.length))
+            throw new ParameterAgentError('parameter_agent_integration_incomplete');
+        const evidence = new Set(report.sources.map(source => source.path));
+        for (const path of [document.schemaPath, document.dataPath, document.platformI18nPath, 'package.json']) {
+            if (path && !evidence.has(path))
+                throw new ParameterAgentError('parameter_agent_evidence_missing');
+        }
+        for (const candidate of implemented) {
+            const field = catalog.find(entry => candidate.fieldPath && entry.key === candidate.fieldPath.join('.'));
+            if (!field || !field.editable || !field.canReset)
+                throw new ParameterAgentError('parameter_agent_field_not_ready');
+            if (field.hasOverride && validateParameterChange(document.schema, document.data, { fieldPath: field.fieldPath, value: field.value }))
+                throw new ParameterAgentError('parameter_agent_field_not_ready');
+            if (!candidate.consumers.length)
+                throw new ParameterAgentError('parameter_agent_consumer_missing');
+        }
+        const packageData = JSON.parse((await readParameterAgentFile(root, 'package.json')).toString('utf8'));
+        for (const script of ['test:parameters', 'build']) {
+            if (typeof packageData.scripts?.[script] !== 'string' || !packageData.scripts[script].trim())
+                throw new ParameterAgentError('parameter_agent_check_script_missing');
+        }
+        task.instanceToken = state.instanceToken;
+        await update(state, task, { status: 'checking', checks: [], error: undefined, receiptId: undefined, sourceDigest: before.digest }, root);
+        const scripts = ['test:parameters', 'build', ...(typeof packageData.scripts?.typecheck === 'string' ? ['typecheck'] : [])];
+        for (const script of scripts) {
+            assertActive();
+            const controller = new AbortController();
+            const abort = () => controller.abort();
+            options.signal?.addEventListener('abort', abort, { once: true });
+            let activityError;
+            const timer = setInterval(() => { try {
+                assertActive();
+            }
+            catch (error) {
+                activityError = error;
+                controller.abort();
+            } }, 200);
+            const startedAt = now();
+            const chunks = [];
+            let outputSize = 0;
+            let outcome;
+            try {
+                outcome = await (options.runCommand ?? runDeveloperCommand)(state, {
+                    processId: `parameter-check-${taskId}-${script.replace(':', '-')}`, cwd: root,
+                    command: `pnpm run ${script}`, timeoutMs: options.timeoutMs ?? (script === 'build' ? 300_000 : 120_000), signal: controller.signal,
+                    onOutput(chunk) { const bytes = Buffer.from(chunk); outputSize += bytes.length; if (outputSize <= 1024 * 1024)
+                        chunks.push(bytes); },
+                });
+            }
+            finally {
+                clearInterval(timer);
+                options.signal?.removeEventListener('abort', abort);
+            }
+            if (activityError)
+                throw activityError;
+            assertActive();
+            task.record.checks.push({ script: script, code: outcome.code ?? null, timedOut: outcome.timedOut, ...(outcome.canceled ? { canceled: true } : {}), logDigest: parameterDigest(Buffer.concat(chunks)), startedAt, finishedAt: now() });
+            await writePrivateParameterTask(state, task, root);
+            if (outcome.code !== 0 || outcome.timedOut || outcome.canceled)
+                throw new ParameterAgentError(outcome.timedOut ? 'parameter_agent_check_timeout' : outcome.canceled ? 'parameter_agent_check_canceled' : 'parameter_agent_check_failed');
+        }
+        assertActive();
+        const after = await parameterInputSnapshot(root);
+        if (after.digest !== before.digest || parameterDigest(await readParameterAgentFile(root, task.record.reportPath, 1024 * 1024)) !== task.reportHash)
+            throw new ParameterAgentError('parameter_agent_inputs_changed');
+        return update(state, task, { status: 'verified', sourceDigest: after.digest, receiptId: randomUUID(), error: undefined }, root);
+    }
+    catch (cause) {
+        const code = errorCode(cause);
+        const status = code === 'ENOENT' ? 'missing' : /stale|changed|expired/.test(code) ? 'stale' : /(?:not_ready|incomplete|consumer_missing|script_missing|evidence_missing)$/.test(code) ? 'needs-verification' : /report_|evidence_invalid|path_invalid/.test(code) ? 'invalid' : 'failed';
+        return update(state, task, { status, error: code === 'ENOENT' ? 'parameter_agent_report_missing' : code, receiptId: undefined }, root);
+    }
+}