witnora 0.20.6 → 0.20.8

package/README.md

@@ -56,8 +56,17 @@ explicit GitHub authorization and is never enabled implicitly.
 ### Customer-owned Gateway
 
 The default Setup Wizard installs and starts a customer-owned Gateway beside
-the Agent automatically. Run the Agent's normal sandbox workflow. Routine
-Gateway operations are available without keeping another terminal open:
+the Agent automatically. For local sandbox runs, launch the Agent through the
+credential wrapper printed by onboarding. It injects the local Gateway binding
+only into that child process, without placing the Gateway token in shell history:
+
+```bash
+npx witnora@latest gateway exec -- python scripts/run_workflow.py
+```
+
+Production Agent platforms should provide the same two environment variables
+through their own secret store. Routine Gateway operations are available
+without keeping another terminal open:
 
 ```bash
 npx witnora@latest gateway status

package/dist/cli.js

@@ -42,6 +42,7 @@ import { renderReleaseEvaluation, runReleaseEvaluation } from "./release-evaluat
 import { runPrivateCapabilityDiscovery } from "./private-discovery.js";
 import { configureManagedWorkflowHarness, doctorCustomerGateway, initializeCustomerGateway, isGatewayDoctorReady, readManagedCustomerGatewayLogs, renderGatewayDoctor, renderManagedGatewayStatus, restartManagedCustomerGateway, runCustomerGateway, startManagedCustomerGateway, statusManagedCustomerGateway, stopManagedCustomerGateway, superviseManagedCustomerGateway, } from "./gateway.js";
 import { installCurrentGatewayService, stopCurrentGatewayOwners, uninstallCurrentGatewayService } from "./gateway-service.js";
+import { runCustomerGatewayCommand } from "./gateway-exec.js";
 import { verifyEvidencePacketV02 } from "./evidence-v02.js";
 process.on("uncaughtException", reportFatalError);
 process.on("unhandledRejection", reportFatalError);
@@ -159,6 +160,7 @@ else if (command === "onboard") {
         repository: readFlag("--repo") ?? process.cwd(),
         template: readFlag("--template") ? parseAgentTemplate(readFlag("--template")) : undefined,
         actionTransport: readActionTransport(readFlag("--action-transport")),
+        waitForActionPathMs: readActionTransport(readFlag("--action-transport")) && !readBoolFlag("--no-wait-for-action-path") ? 10 * 60 * 1_000 : 0,
         openBrowser: readBoolFlag("--no-browser") ? async () => { } : undefined,
     });
 }
@@ -276,6 +278,24 @@ else if (command === "gateway") {
         }, () => stopManagedCustomerGateway({ repository, dir, configHome }));
         process.stdout.write(readBoolFlag("--json") ? `${JSON.stringify(result, null, 2)}\n` : renderManagedGatewayStatus(result));
     }
+    else if (action === "exec") {
+        const boundary = process.argv.indexOf("--", 4);
+        const wrapperArgs = boundary >= 0 ? process.argv.slice(4, boundary) : [];
+        const commandArgs = boundary >= 0 ? process.argv.slice(boundary + 1) : [];
+        if (!commandArgs[0])
+            throw new Error("Use witnora gateway exec [--repo <path>] [--dir <path>] -- <agent command> [arguments].");
+        const wrapperFlag = (name) => {
+            const index = wrapperArgs.indexOf(name);
+            return index >= 0 ? wrapperArgs[index + 1] : undefined;
+        };
+        const result = await runCustomerGatewayCommand({
+            repository: wrapperFlag("--repo") ?? process.cwd(),
+            gatewayDirectory: wrapperFlag("--dir"),
+            command: commandArgs[0],
+            args: commandArgs.slice(1),
+        });
+        process.exitCode = result.exitCode;
+    }
     else if (action === "run") {
         await runCustomerGateway({ repository: readFlag("--repo") ?? process.cwd(), dir: readFlag("--dir") });
     }
@@ -297,7 +317,7 @@ else if (command === "gateway") {
         process.stdout.write(`Configured the Managed Workflow Harness for ${result.config.workflowIds?.length ?? "all active"} Workflow Contract(s).\nConfig: ${result.path}\nRestart the managed Gateway to activate it.\n`);
     }
     else {
-        throw new Error("Use witnora gateway init|doctor|start|status|logs|restart|repair|service|stop|run|workflow-harness.");
+        throw new Error("Use witnora gateway init|doctor|start|status|logs|restart|repair|service|stop|exec|run|workflow-harness.");
     }
 }
 else if (command === "discover") {

package/dist/gateway-exec.js

@@ -0,0 +1,42 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+export async function runCustomerGatewayCommand(options) {
+    const repository = resolve(options.repository);
+    const gatewayDirectory = resolve(options.gatewayDirectory ?? join(repository, ".witnora", "gateway"));
+    const [config, secrets] = await Promise.all([
+        readJson(join(gatewayDirectory, "gateway.json"), "Gateway configuration"),
+        readJson(join(gatewayDirectory, "secrets.json"), "Gateway secrets"),
+    ]);
+    const host = typeof config.host === "string" && config.host.trim() ? config.host.trim() : "";
+    const port = Number(config.port);
+    const gatewayToken = typeof secrets.gatewayToken === "string" ? secrets.gatewayToken.trim() : "";
+    if (!host || !Number.isInteger(port) || port < 1 || port > 65_535 || !gatewayToken) {
+        throw new Error("The local Gateway binding is incomplete. Run witnora onboard from this repository before starting the Agent workflow.");
+    }
+    return await new Promise((resolveChild, rejectChild) => {
+        const child = spawn(options.command, options.args ?? [], {
+            cwd: repository,
+            env: {
+                ...process.env,
+                WITNORA_GATEWAY_URL: `http://${host}:${port}`,
+                WITNORA_GATEWAY_TOKEN: gatewayToken,
+            },
+            stdio: "inherit",
+            windowsHide: true,
+        });
+        child.once("error", (error) => rejectChild(new Error(`Could not start the Agent workflow command: ${error.message}`)));
+        child.once("exit", (code) => resolveChild({ exitCode: code ?? 1 }));
+    });
+}
+async function readJson(path, label) {
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error("expected an object");
+        return value;
+    }
+    catch {
+        throw new Error(`${label} is unavailable. Run witnora onboard from this repository before starting the Agent workflow.`);
+    }
+}

package/dist/onboard.js

@@ -304,7 +304,7 @@ export async function runOnboard(options) {
         const runtimeReadiness = doctor.overall === "READY_FOR_RUNTIME" && runtimeBinding
             ? { state: "LOCAL_SANDBOX_READY", checkedAt: new Date().toISOString(), limitations: [] }
             : { state: "RECORDED_ONLY", checkedAt: new Date().toISOString(), limitations: [runtimeLimitation ?? "The local sandbox Runtime worker has not established exact adapter, probe, source-key, identity, mandate, and readiness bindings."] };
-        const actionTransportTest = options.actionTransport
+        let actionTransportTest = options.actionTransport
             ? await runActionTransportTest({
                 transport: options.actionTransport,
                 repository: repositoryPath,
@@ -317,12 +317,60 @@ export async function runOnboard(options) {
                 generatedFiles,
             })
             : undefined;
+        const localWorkflowCommand = await detectLocalWorkflowCommand(repositoryPath);
+        const cliVersion = await currentCliVersion();
+        const agentRunCommand = localWorkflowCommand
+            ? `npx --yes witnora@${cliVersion} gateway exec -- ${localWorkflowCommand.join(" ")}`
+            : undefined;
         await reportInstall(requestFetch, server, token.projectId, token.apiKey, setupPlan.id, {
             status: "verified", attemptId, generatedFiles: relativeGeneratedFiles(repositoryPath, generatedFiles), runtimeReadiness,
             connectedAgent: agentIdentity,
+            agentRunCommand,
             ...(runtimeBinding ? { runtimeBinding } : {}),
         });
-        output(`\nWitnora Setup Autopilot completed for ${repository.name}.\n`);
+        if (actionTransportTest?.state === "WAITING_FOR_ACTION_PATH" && (options.waitForActionPathMs ?? 0) > 0) {
+            output("\nBase setup is complete. Onboarding is waiting for the Business Task and Action path; it has not claimed completion.\n");
+            output(agentRunCommand
+                ? `Open a second terminal in this repository and run the Agent safely once:\n${agentRunCommand}\n`
+                : "Run the Agent normally in its sandbox. If it has no work now, you may enter the workspace and finish Action verification after its first real run.\n");
+            output(`Keep this command open for up to ${Math.max(1, Math.ceil((options.waitForActionPathMs ?? 0) / 60_000))} minutes. It will finish automatically after you confirm the Business Task in the browser; no second onboard command is required. Press Ctrl+C to pause safely.\n`);
+            const lateActivation = await waitForRealPathActivation({
+                repository: repositoryPath, server, projectId: token.projectId, apiKey: token.apiKey,
+                env: options.env, fetch: requestFetch, sleep: options.sleep, timeoutMs: options.waitForActionPathMs ?? 0,
+            });
+            if (lateActivation) {
+                realPathActivation = lateActivation;
+                generatedFiles.push(...lateActivation.generatedFiles);
+                const harness = await activateManagedWorkflowHarness({ repository: repositoryPath, realPathActivations: lateActivation.activations, previousGeneratedModuleSha256: lateActivation.previousGeneratedModuleSha256 });
+                if (harness.created)
+                    generatedFiles.push(harness.path);
+                assuranceHarnessReadiness = { state: "ACTIVE" };
+                httpActionSetup = await configureCustomerHttpAction({ repository: repositoryPath, activations: lateActivation.activations });
+                generatedFiles.push(...httpActionSetup.generatedFiles);
+                if (harness.changed || httpActionSetup.changed) {
+                    await stopGatewayOwners();
+                    if (!options.gatewayLifecycle) {
+                        await installCurrentGatewayService({ repository: repositoryPath, cliEntry: fileURLToPath(new URL("./cli.js", import.meta.url)), configHome: options.configHome });
+                        managedGateway = await waitForInstalledGatewayService({ repository: repositoryPath, fetch: requestFetch, sleep: options.sleep, timeoutMs: options.timeoutMs });
+                    }
+                    else {
+                        managedGateway = await gatewayLifecycle.start({ repository: repositoryPath, configHome: options.configHome, fetch: requestFetch, output });
+                    }
+                }
+                actionTransportTest = await runActionTransportTest({
+                    transport: options.actionTransport, repository: repositoryPath, server, projectId: token.projectId, apiKey: token.apiKey,
+                    repositoryIdentity: repository, httpActionReady: httpActionSetup.state === "READY" && Boolean(httpActionSetup.action),
+                    fetch: requestFetch, generatedFiles,
+                });
+                await reportInstall(requestFetch, server, token.projectId, token.apiKey, setupPlan.id, {
+                    status: "verified", attemptId, generatedFiles: relativeGeneratedFiles(repositoryPath, generatedFiles), runtimeReadiness,
+                    connectedAgent: agentIdentity, agentRunCommand, ...(runtimeBinding ? { runtimeBinding } : {}),
+                });
+            }
+        }
+        output(actionTransportTest?.state === "WAITING_FOR_ACTION_PATH"
+            ? `\nWitnora base setup completed for ${repository.name}; Action onboarding is paused and still pending.\n`
+            : `\nWitnora Setup Autopilot completed for ${repository.name}.\n`);
         output(`Project: ${token.projectId}\nTemplate: ${repository.template} (${repository.kind})\n`);
         output(`Credentials: ${credentialsPath}\nSelf-test receipt: ${receiptPath}\n`);
         output(`Private discovery: ${discovery.capabilityCount} capability group(s); ${discovery.unknownCapabilityCount} pending confirmation.\n`);
@@ -346,8 +394,11 @@ export async function runOnboard(options) {
             output(`Action transport: ${actionTransportTest.transport.toUpperCase()} is waiting for one exact sandbox Task/action path. ${actionTransportTest.limitation}\n`);
         }
         output(actionTransportTest?.state === "WAITING_FOR_ACTION_PATH"
-            ? `Base Gateway connected, but ${actionTransportTest.transport.toUpperCase()} Action is not verified yet. Run the Agent's normal sandbox workflow from this repository; there is no Run button in Overview. Once Overview receives the activity, confirm one sandbox Business Task and choose its exact discovered Agent action, then rerun this same command.\n`
+            ? `Base Gateway connected, but ${actionTransportTest.transport.toUpperCase()} Action is not verified yet. Run the Agent once and confirm its Business Task in the browser. Recovery only: rerun this command if the original waiting process was closed.\n`
             : "Connected. Nora is monitoring this Agent. Run it normally whenever it is ready; the first source-signed activity will appear automatically without blocking setup.\n");
+        output(localWorkflowCommand
+            ? `Local sandbox command: ${agentRunCommand}\n`
+            : `For a local sandbox workflow, use npx --yes witnora@${cliVersion} gateway exec -- <your normal sandbox command> so the Gateway token stays out of shell history.\n`);
         return { projectId: token.projectId, connectionName: token.connectionName, credentialsPath, template: repository.template,
             repositoryKind: repository.kind, generatedFiles, receiptPath, discovery, setupPlanId: setupPlan.id,
             gatewayDirectory: join(repositoryPath, ".witnora", "gateway"), gatewayArchiveDirectory: gatewayMigration?.archiveDirectory,
@@ -407,6 +458,21 @@ async function loadMatchingOnboardConnection(options) {
         return undefined;
     }
 }
+async function waitForRealPathActivation(options) {
+    const sleep = options.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+    let waited = 0;
+    let delay = 2_000;
+    while (waited < options.timeoutMs) {
+        const activation = await activateRealPathIntegrations(options);
+        if (activation.activations.length)
+            return activation;
+        const interval = Math.min(delay, options.timeoutMs - waited);
+        await sleep(interval);
+        waited += interval;
+        delay = Math.min(15_000, Math.round(delay * 1.5));
+    }
+    return undefined;
+}
 async function runActionTransportTest(options) {
     if (!options.httpActionReady)
         return {
@@ -594,6 +660,17 @@ function relativeGeneratedFiles(repositoryPath, files) {
     return files.map((file) => file.startsWith(repositoryPath) ? file.slice(repositoryPath.length + 1).replaceAll("\\", "/") : file).filter(Boolean);
 }
 function randomSuffix() { return Math.random().toString(36).slice(2, 10); }
+async function detectLocalWorkflowCommand(repositoryPath) {
+    if (await exists(join(repositoryPath, "scripts", "run_workflow.py")))
+        return ["python", "scripts/run_workflow.py"];
+    if (await exists(join(repositoryPath, "scripts", "run-workflow.mjs")))
+        return ["node", "scripts/run-workflow.mjs"];
+    return undefined;
+}
+async function currentCliVersion() {
+    const manifest = await optionalJson(fileURLToPath(new URL("../package.json", import.meta.url)));
+    return typeof manifest?.version === "string" && manifest.version.trim() ? manifest.version.trim() : "latest";
+}
 export async function inspectRepository(repositoryPath, explicitTemplate) {
     const entries = await readdir(repositoryPath, { withFileTypes: true });
     const names = entries.map((entry) => entry.name).sort();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "witnora",
-  "version": "0.20.6",
+  "version": "0.20.8",
   "description": "Independent assurance for covered agent action paths across models and frameworks.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",