witnora 0.20.6 → 0.20.7

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);
@@ -276,6 +277,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 +316,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

@@ -317,6 +317,8 @@ export async function runOnboard(options) {
                 generatedFiles,
             })
             : undefined;
+        const localWorkflowCommand = await detectLocalWorkflowCommand(repositoryPath);
+        const cliVersion = await currentCliVersion();
         await reportInstall(requestFetch, server, token.projectId, token.apiKey, setupPlan.id, {
             status: "verified", attemptId, generatedFiles: relativeGeneratedFiles(repositoryPath, generatedFiles), runtimeReadiness,
             connectedAgent: agentIdentity,
@@ -348,6 +350,9 @@ export async function runOnboard(options) {
         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`
             : "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: npx --yes witnora@${cliVersion} gateway exec -- ${localWorkflowCommand.join(" ")}\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,
@@ -594,6 +599,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.7",
   "description": "Independent assurance for covered agent action paths across models and frameworks.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",