npm - @zq-silk/yui - Versions diffs - 0.15.8 → 0.15.11 - Mend

@zq-silk/yui 0.15.8 → 0.15.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (151) hide show

package/ARCHITECTURE.md +2 -0
package/ARCHITECTURE.zh-CN.md +151 -0
package/README.md +211 -14
package/dist/agent/launchEnvironment.js +7 -0
package/dist/artifacts/artifactCapability.js +74 -0
package/dist/artifacts/artifactCommitLock.js +249 -0
package/dist/artifacts/artifactPaths.js +151 -0
package/dist/artifacts/gitArtifactRef.js +146 -0
package/dist/artifacts/managedGit.js +332 -0
package/dist/artifacts/taskArtifactRepository.js +277 -0
package/dist/cli/commandCatalog.js +40 -16
package/dist/cli/interactionPolicy.js +3 -3
package/dist/cli/updateOrchestrator.js +24 -1
package/dist/cli/updatePorts.js +7 -3
package/dist/cli/upgradeCommand.js +42 -2
package/dist/cli.js +403 -93
package/dist/commands/globalRoleCommands.js +314 -4
package/dist/commands/operatorCommands.js +33 -2
package/dist/commands/projectCommands.js +6 -7
package/dist/commands/releaseCommands.js +18 -0
package/dist/commands/taskActivationCommands.js +22 -0
package/dist/commands/taskActor.js +25 -0
package/dist/commands/taskCommands.js +846 -155
package/dist/commands/taskIntegrationCommands.js +16 -38
package/dist/commands/taskIntegrationQueueCommands.js +1 -1
package/dist/commands/taskRemoteDeliveryCommand.js +6 -6
package/dist/commands/taskRoleRuntimeStatus.js +35 -0
package/dist/context/runContextPack.js +28 -16
package/dist/context/taskContext.js +64 -5
package/dist/controller/agentHostObservation.js +155 -0
package/dist/controller/clientRuntime.js +17 -2
package/dist/controller/controller.js +11 -2
package/dist/controller/fileSchedulerStoreAdapter.js +446 -13
package/dist/controller/globalInputDelivery.js +119 -0
package/dist/controller/jobControl.js +6 -2
package/dist/controller/resourceInventory.js +14 -4
package/dist/controller/resourceInventoryLinux.js +2 -6
package/dist/controller/runtime.js +81 -6
package/dist/controller/runtimeEventInbox.js +32 -3
package/dist/controller/runtimeEventProcessor.js +26 -6
package/dist/controller/runtimeHookRunFence.js +75 -19
package/dist/controller/structuredProviderObservation.js +133 -70
package/dist/coordination/workMailboxQueue.js +5 -0
package/dist/execution/workItemExecutionProjection.js +1 -1
package/dist/executor/agentExecutor.js +64 -4
package/dist/executor/executorRegistry.js +3 -0
package/dist/executor/fileRoleLaunchPlanner.js +78 -118
package/dist/integration/deliveryObligation.js +2 -1
package/dist/integration/gitIntegrationService.js +312 -382
package/dist/integration/integrationAttempt.js +30 -4
package/dist/integration/integrationQueueService.js +7 -7
package/dist/integration/integrationSourceApplication.js +323 -0
package/dist/kernel/builtinCapabilities.js +32 -24
package/dist/message/globalInterrupt.js +33 -0
package/dist/message/inputControlResolution.js +106 -0
package/dist/message/message.js +423 -0
package/dist/message/messageContinuation.js +126 -3
package/dist/message/taskInterrupt.js +34 -0
package/dist/observability/orchestrationMetrics.js +1 -1
package/dist/plugins/pluginService.js +11 -3
package/dist/release/releaseHandover.js +22 -0
package/dist/release/releaseWorkflowPorts.js +15 -7
package/dist/repository/gitWorkspace.js +72 -15
package/dist/repository/taskWorkspaceCoordinator.js +134 -0
package/dist/repository/taskWorkspacePreparer.js +120 -49
package/dist/repository/workItemCandidateSnapshot.js +34 -0
package/dist/resources/projectResource.js +0 -48
package/dist/resources/projectResourceService.js +3 -81
package/dist/resources/resourceDiscovery.js +3 -2
package/dist/runtime/agentHost.js +152 -72
package/dist/runtime/agentHostCompatibility.js +127 -0
package/dist/runtime/agentHostProtocol.js +53 -0
package/dist/runtime/executionEnvironment.js +0 -19
package/dist/runtime/launchBroker.js +6 -0
package/dist/runtime/sessionReconciliation.js +4 -4
package/dist/runtime/taskRuntimeIsolation.js +30 -6
package/dist/runtime/tmuxAdapters.js +5 -3
package/dist/scheduler/operatorEvent.js +4 -0
package/dist/scheduler/taskExecutionProjection.js +12 -1
package/dist/scheduler/wakeReason.js +7 -1
package/dist/scheduler/wakeupQueue.js +2 -0
package/dist/setup/setupCommand.js +29 -16
package/dist/storage/homeLayout.js +130 -0
package/dist/storage/migrations/artifactsToGit.js +338 -0
package/dist/storage/migrations/collapseWorktreeLayout.js +963 -0
package/dist/storage/migrations/integrationContinuation.js +104 -0
package/dist/storage/migrations/submitIntent.js +126 -0
package/dist/storage/migrations/unifyHomeLayout.js +925 -0
package/dist/storage/sqliteSchema.js +173 -7
package/dist/storage/sqliteStore.js +41 -22
package/dist/storage/storageVersions.js +1 -1
package/dist/storage/storeRpc.js +2 -1
package/dist/storage/upgrade/upgradeOrchestrator.js +95 -2
package/dist/task/archiveDiagnostics.js +128 -0
package/dist/task/nextAction.js +44 -11
package/dist/task/taskActivation.js +26 -0
package/dist/task/taskActivationService.js +85 -69
package/dist/task/taskSubmission.js +236 -0
package/dist/web/assets/client/app.js +58 -2
package/dist/web/assets/client/components.js +1 -0
package/dist/web/assets/client/i18n.js +6 -0
package/dist/web/assets/client/taskSurface.js +202 -7
package/dist/web/assets/client/view.js +7 -4
package/dist/web/assets/shell.js +23 -0
package/dist/web/assets/styles/layout.js +1 -1
package/dist/web/assets/styles/widgets.js +12 -0
package/dist/web/webServer.js +135 -4
package/dist/web/webSnapshot.js +4 -3
package/dist/web/webTaskSurface.js +225 -8
package/dist/workItem/workItem.js +14 -10
package/dist/workspace/workItemChangeSetManager.js +18 -2
package/docs/agent-result-consumption.md +2 -0
package/docs/agent-result-consumption.zh-CN.md +81 -0
package/docs/agent-runtime-drivers.md +2 -0
package/docs/agent-runtime-drivers.zh-CN.md +77 -0
package/docs/architecture/README.md +44 -32
package/docs/architecture/README.zh-CN.md +43 -0
package/docs/architecture/capabilities-and-resources.md +118 -79
package/docs/architecture/capabilities-and-resources.zh-CN.md +83 -0
package/docs/managed-turn-and-session-runtime.md +2 -0
package/docs/managed-turn-and-session-runtime.zh-CN.md +180 -0
package/docs/observability/README.md +2 -0
package/docs/observability/README.zh-CN.md +71 -0
package/docs/plugin-sdk.md +320 -217
package/docs/plugin-sdk.zh-CN.md +293 -0
package/docs/provider-runtime.md +2 -0
package/docs/provider-runtime.zh-CN.md +132 -0
package/docs/release-workflow.md +41 -0
package/docs/release-workflow.zh-CN.md +266 -0
package/docs/roles-and-configuration.md +2 -0
package/docs/roles-and-configuration.zh-CN.md +96 -0
package/docs/sqlite-control-plane-design.md +225 -1
package/docs/sqlite-control-plane-design.zh-CN.md +62 -0
package/docs/task-dag-semantics.md +80 -57
package/docs/task-dag-semantics.zh-CN.md +59 -0
package/docs/task-delivery.md +2 -0
package/docs/task-delivery.zh-CN.md +82 -0
package/docs/task-local-identity.md +2 -0
package/docs/task-local-identity.zh-CN.md +58 -0
package/docs/testing/verification-levels.md +26 -0
package/docs/testing/verification-levels.zh-CN.md +80 -0
package/i18n/README.zh-CN.md +199 -10
package/package.json +2 -1
package/skills/yui-leader/SKILL.md +88 -331
package/skills/yui-leader/references/execution.md +405 -0
package/skills/yui-leader/references/integration.md +52 -2
package/skills/yui-leader/references/planning.md +109 -0
package/skills/yui-leader/references/task-plugins.md +8 -4
package/skills/yui-operator/SKILL.md +22 -4
package/skills/yui-runtime/SKILL.md +27 -0
package/skills/yui-runtime/references/publication.md +20 -0

package/dist/cli/commandCatalog.js CHANGED Viewed

@@ -380,12 +380,12 @@ const taskChildren = [
     { name: "show", summary: "Show a Task.", usage: "yui task show <id>" },
     {
         name: "artifact",
-        summary: "Save fixed Task results and read history without the original Runtime.",
-        sections: [{ id: "manage", title: "Commands", entries: ["list", "show", "save"] }],
+        summary: "Save Task files in local Git and read current or commit-pinned content.",
+        sections: [{ id: "manage", title: "Commands", entries: ["list", "read", "save"] }],
         children: [
             { name: "list", summary: "List saved Task artifacts.", usage: "yui task artifact list <task>" },
-            { name: "show", summary: "Read one saved artifact.", usage: "yui task artifact show <task> <artifact-id>" },
-            { name: "save", summary: "Save content, a version, receipt, or reference.", usage: "yui task artifact save <task> <artifact-json>" }
+            { name: "read", summary: "Read a file at HEAD or an exact commit.", usage: "yui task artifact read <task> <relative-path> [<commit>]" },
+            { name: "save", summary: "Save and locally commit one file.", usage: "yui task artifact save <task> <relative-path> <content> [--message <text>] [--expected-head <commit>]", options: ["--message", "--expected-head"] }
         ]
     },
     {
@@ -408,8 +408,8 @@ const taskChildren = [
     },
     {
         name: "archive",
-        summary: "Archive a Task after confirming the main worktree outcome.",
-        usage: "yui task archive <id> (--integrated [--force]|--abandon)",
+        summary: "Archive a terminal Task; explicit --force commits despite delivery/cleanup warnings, retaining unsafe resources.",
+        usage: "yui task archive <id> (--integrated|--abandon) [--force]",
         options: ["--integrated", "--abandon", "--force"]
     },
     { name: "reconcile", summary: "Run one immediate Controller reconciliation.", usage: "yui task reconcile <id>" },
@@ -435,7 +435,7 @@ const taskChildren = [
     {
         name: "message",
         summary: "Manage durable Task messages.",
-        sections: [{ id: "manage", title: "Commands", entries: ["send", "handoff", "list", "show", "update", "retire"] }],
+        sections: [{ id: "manage", title: "Commands", entries: ["send", "queue", "steer", "handoff", "list", "show", "update", "retire"] }],
         children: [
             {
                 name: "handoff",
@@ -445,14 +445,29 @@ const taskChildren = [
             },
             {
                 name: "send",
-                summary: "Send a Task message.",
-                usage: "yui task message send <id> (<body>|--body-file <path|->) [--wake-policy leader|none] [--to <role> --work-item <id>|--review-round <id>]",
-                options: ["--body-file", "--wake-policy", "--to", "--work-item", "--review-round"],
+                summary: "Send a Task message. An unaddressed user/operator message carries a submission intent (record|discuss|develop) and an optional idempotency key.",
+                usage: "yui task message send <id> (<body>|--body-file <path|->) [--intent record|discuss|develop] [--request-id <key>] [--wake-policy leader|none] [--to <role> --work-item <id>|--review-round <id>]",
+                options: ["--body-file", "--intent", "--request-id", "--wake-policy", "--to", "--work-item", "--review-round"],
                 optionValues: {
+                    "--intent": ["record", "discuss", "develop"],
                     "--wake-policy": ["leader", "none"]
                 },
                 fileOptions: ["--body-file"]
             },
+            {
+                name: "queue",
+                summary: "Queue an input for delivery at the recipient's next legal opportunity (idempotent by request id).",
+                usage: "yui task message queue <id> (<body>|--body-file <path|->) --request-id <id> [--to <role> --work-item <id>|--review-round <id>]",
+                options: ["--body-file", "--request-id", "--to", "--work-item", "--review-round"],
+                fileOptions: ["--body-file"]
+            },
+            {
+                name: "steer",
+                summary: "Steer only a Role's exact current native Turn; saved and reported without fallback when unsupported.",
+                usage: "yui task message steer <id> (<body>|--body-file <path|->) --request-id <id> --expected-target <turn> --to <role> [--work-item <id>|--review-round <id>]",
+                options: ["--body-file", "--request-id", "--expected-target", "--to", "--work-item", "--review-round"],
+                fileOptions: ["--body-file"]
+            },
             {
                 name: "list",
                 summary: "List Task messages.",
@@ -621,7 +636,7 @@ const taskChildren = [
         summary: "Manage Roles within a Task.",
         sections: [{ id: "manage", title: "Commands", entries: [
                     "add", "list", "status", "show", "update", "remove", "bind", "unbind",
-                    "session", "view", "takeover", "release"
+                    "session", "interrupt", "view", "takeover", "release"
                 ] }],
         children: [
             {
@@ -679,6 +694,12 @@ const taskChildren = [
                 summary: "Attach read-only to an independent Provider presentation surface.",
                 usage: "yui task role view <task> <role>"
             },
+            {
+                name: "interrupt",
+                summary: "Interrupt a Role's exact current native Turn via native cancel; optionally deliver a saved Message once after a proven terminal.",
+                usage: "yui task role interrupt <task> <role> --expected-target <turn> [--then-message <task/message>] [--request-id <id>]",
+                options: ["--expected-target", "--then-message", "--request-id"]
+            },
             {
                 name: "takeover",
                 summary: "Enter the PTY input gateway for an independent Provider process.",
@@ -705,7 +726,7 @@ const taskChildren = [
         children: [
             {
                 name: "create",
-                summary: "Create a work item.",
+                summary: "Create a separately managed result; a coherent Task may use zero WorkItems. Omit --role for Leader-direct execution; --role (including leader) selects a managed AgentRun executor. Isolate writable direct work before editing, then submit, integrate and accept its Candidate.",
                 usage: "yui task work create <task> <title> [--project <project> ...] [--base-ref <project>=<ref> ...] [--objective <text>] [--accept <criterion> ...] [--after <work> ...] [--role <name>]",
                 options: ["--project", "--base-ref", "--objective", "--accept", "--after", "--role"]
             },
@@ -921,7 +942,7 @@ const taskChildren = [
             },
             {
                 name: "abort",
-                summary: "Abandon a running or blocked Integration Attempt.",
+                summary: "Abandon an unadvanced Integration while preserving evidence; reconcile an already-applied target.",
                 usage: "yui task integration abort <task>/<integration> --reason <text>",
                 options: ["--reason"]
             },
@@ -1286,9 +1307,12 @@ export const ROOT_COMMAND = buildNode({
                 },
                 {
                     name: "submit",
-                    summary: "Submit work through the Operator.",
-                    usage: "yui operator submit (<body>|--body-file <path|->) [--task <id>]",
-                    options: ["--task", "--body-file"],
+                    summary: "Submit work through the Operator with a submission intent (record|discuss|develop); a task-less submit opens a Draft. An optional idempotency key makes a retry safe.",
+                    usage: "yui operator submit (<body>|--body-file <path|->) [--task <id>] [--intent record|discuss|develop] [--request-id <key>]",
+                    options: ["--task", "--body-file", "--intent", "--request-id"],
+                    optionValues: {
+                        "--intent": ["record", "discuss", "develop"]
+                    },
                     fileOptions: ["--body-file"]
                 }
             ]

package/dist/cli/interactionPolicy.js CHANGED Viewed

@@ -574,9 +574,9 @@ export const INTERACTION_POLICIES = Object.freeze([
                 entity: "integration-attempt",
                 provider: "integration-attempts",
                 actionTarget: true,
-                ...(command === "continue" ? { statuses: ["blocked", "validating"] } : {}),
-                ...(command === "resolve" ? { statuses: ["blocked"] } : {}),
-                ...(command === "abort" ? { statuses: ["running", "blocked"] } : {})
+                ...(command === "continue" ? { statuses: ["running", "conflicted", "blocked", "validating"] } : {}),
+                ...(command === "resolve" ? { statuses: ["blocked", "conflicted"] } : {}),
+                ...(command === "abort" ? { statuses: ["running", "conflicted", "blocked", "validating"] } : {})
             }],
         ...(command === "resolve"
             ? { trailingOptions: { "--option": "value", "--rationale": "value" } }

package/dist/cli/updateOrchestrator.js CHANGED Viewed

@@ -101,7 +101,30 @@ function runStagedUpdate(ports, staged, home) {
         const captured = captureControllerLifecycle(ports, staged.version, home);
         if ("outcome" in captured)
             return captured;
-        return activateAndVerify(ports, staged, home, captured.lifecycle, preflight);
+        // An older Controller can finish a launch between preflight and drain.
+        // Recheck after its exact stop, before changing the install or storage.
+        let fencedPreflight;
+        try {
+            fencedPreflight = ports.preflight(staged, home);
+        }
+        catch (error) {
+            return restoreControllerOrReport(ports, home, captured.lifecycle, {
+                outcome: "aborted", phase: "preflight",
+                message: `Quiesced compatibility preflight failed: ${messageOf(error)}`,
+                action: "The install and storage are unchanged; inspect the compatibility failure before retrying.",
+                recoverable: true, version: staged.version
+            });
+        }
+        if (fencedPreflight.status === "blocked") {
+            return restoreControllerOrReport(ports, home, captured.lifecycle, {
+                outcome: "aborted", phase: "preflight",
+                message: fencedPreflight.message, action: fencedPreflight.action,
+                recoverable: true, version: staged.version,
+                ...(fencedPreflight.blockers === undefined ? {} : { blockers: fencedPreflight.blockers }),
+                ...(fencedPreflight.sceneUnchanged === true ? { sceneUnchanged: true } : {})
+            });
+        }
+        return activateAndVerify(ports, staged, home, captured.lifecycle, fencedPreflight);
     }
     finally {
         releaseHandover?.();

package/dist/cli/updatePorts.js CHANGED Viewed

@@ -25,14 +25,15 @@
  *    mismatch fails closed.
  */
 import { spawnSync } from "node:child_process";
-import { accessSync, constants, existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { accessSync, constants, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
 import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runtimeError } from "../errors/cliError.js";
 import { isConcreteVersion } from "../domain/validation.js";
 import { STORAGE_DOCTOR_CHECK_NAMES } from "../doctor/doctor.js";
 import { acquireHandoverLock } from "../release/runtimeRelease.js";
+import { updateStagingRoot } from "../storage/homeLayout.js";
+import { resolveYuiHome } from "../storage/taskStore.js";
 const PACKAGE_NAME = "@zq-silk/yui";
 const PACKAGE_SPEC = `${PACKAGE_NAME}@latest`;
 function resolveExecutable(command, environmentPath) {
@@ -64,7 +65,7 @@ function failedSpawnResult(message) {
     };
 }
 /** Build the real ports. `spawn` is injectable so tests avoid real installs. */
-export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot = tmpdir()) {
+export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot = updateStagingRoot(resolveYuiHome(environment))) {
     // The production adapter must not let a later PATH change select a
     // different npm during staging, activation, or recovery. Test doubles are
     // intentionally left untouched so deterministic tests can dispatch on the
@@ -105,6 +106,9 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
                 throw runtimeError(`Refusing to stage a non-concrete version (${String(version)}): only an exact `
                     + "major.minor.patch version can be pinned for an update.");
             }
+            // The Home staging parent may not exist yet on a Home that has never
+            // run an update; create it (private) before minting a throwaway prefix.
+            mkdirSync(stagingRoot, { recursive: true, mode: 0o700 });
             const stagingPath = mkdtempSync(join(stagingRoot, "yui-update-stage-"));
             let ownsStaging = true;
             try {

package/dist/cli/upgradeCommand.js CHANGED Viewed

@@ -1,6 +1,8 @@
 /** `yui upgrade` plans or applies the supported linear storage migration chain. */
 import { runStorageUpgrade } from "../storage/upgrade/upgradeOrchestrator.js";
-import { ensureFileTaskController, stopFileTaskController } from "../controller/clientRuntime.js";
+import { ensureFileTaskController, ensureFileTaskControllerIdentity, stopFileTaskController } from "../controller/clientRuntime.js";
+import { callController, ControllerClientError } from "../core/controllerClient.js";
+import { spawn } from "node:child_process";
 import { runtimeError, usageError } from "../errors/cliError.js";
 import { acquireHandoverLock, isForeignHandoverLockHeld, isHandoverLockHeld } from "../release/runtimeRelease.js";
 /**
@@ -43,12 +45,29 @@ async function runInteractiveUpgrade(home, environment) {
     const handover = acquireHandoverLock(home);
     let controllerWasRunning = false;
     try {
+        const previous = await captureUpgradeController(home);
         const stopped = await stopFileTaskController(home, {
             environment,
-            handoverOwnerPid: process.pid
+            handoverOwnerPid: process.pid,
+            ...(previous === undefined ? {} : { expectedPid: previous.pid })
         });
         controllerWasRunning = stopped.stopped;
         const result = await runStorageUpgrade({ home, mode: "execute" });
+        if (controllerWasRunning && result.outcome === "blocked") {
+            if (previous === undefined) {
+                throw runtimeError("Upgrade was blocked without changing storage; the stopped Controller identity is unknown. Keep the Home quiesced.");
+            }
+            await ensureFileTaskControllerIdentity(home, previous.identity, {
+                environment, handoverOwnerPid: process.pid,
+                spawnController: (_home, launchEnvironment) => {
+                    const child = spawn(previous.identity.executablePath, [...previous.identity.args], {
+                        env: launchEnvironment, detached: true, stdio: "ignore"
+                    });
+                    child.unref();
+                    return child.pid;
+                }
+            });
+        }
         if (controllerWasRunning
             && (result.outcome === "upgraded" || result.outcome === "already-current")) {
             try {
@@ -70,6 +89,27 @@ async function runInteractiveUpgrade(home, environment) {
         handover.release();
     }
 }
+async function captureUpgradeController(home) {
+    let value;
+    try {
+        value = await callController(home, "controller.identity", {});
+    }
+    catch (error) {
+        if (error instanceof ControllerClientError && error.code === "CONTROLLER_NOT_RUNNING")
+            return undefined;
+        throw error;
+    }
+    const identity = value;
+    if (!Number.isSafeInteger(identity.pid) || identity.pid < 1
+        || typeof identity.executablePath !== "string" || !identity.executablePath
+        || !Array.isArray(identity.args) || identity.args.some(arg => typeof arg !== "string")
+        || typeof identity.version !== "string" || !identity.version) {
+        throw runtimeError("Cannot capture the exact Controller for a reversible upgrade preflight.");
+    }
+    return { pid: identity.pid, identity: {
+            executablePath: identity.executablePath, args: identity.args, version: identity.version
+        } };
+}
 async function runUpdateOwnedUpgrade(home, environment) {
     const ownerText = environment.YUI_UPDATE_HANDOVER_OWNER_PID;
     const ownerPid = ownerText === undefined ? Number.NaN : Number(ownerText);