@anna-ai/cli 0.1.12 → 0.1.16

package/dist/agent-DUmINbo4.js

@@ -0,0 +1,372 @@
+import { canonicalHost } from "./credentials-BTv2IfUZ.js";
+import { hostOf, mintAppSession, requireAccount, withCode } from "./dev-account-DCyjamBa.js";
+import { resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+
+//#region src/executa/agent.ts
+/** JSON-RPC error codes from matrix/src/executa/protocol.py. */
+const AGENT_ERR_NOT_GRANTED = -32041;
+const AGENT_ERR_SESSION_NOT_FOUND = -32042;
+const AGENT_ERR_INVALID_REQUEST = -32043;
+const AGENT_ERR_PROVIDER_ERROR = -32046;
+const AGENT_ERR_RUN_TOO_LARGE = -32047;
+const MAX_FRAMES_PER_RUN = 4096;
+var AgentBridge = class {
+	mocks = [];
+	/** uuid → minted session token (one entry per `session.create`). */
+	sessions = new Map();
+	constructor(opts) {
+		this.opts = opts;
+		if (opts.mode === "mock" && opts.mockFile) {
+			const path = resolve(opts.mockFile);
+			if (existsSync(path)) for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
+				if (!line.trim() || line.startsWith("#")) continue;
+				try {
+					this.mocks.push(JSON.parse(line));
+				} catch {}
+			}
+		}
+	}
+	async call(method, params) {
+		if (this.opts.mode === "off") throw withCode(new Error("agent reverse-RPC disabled — rerun without `--no-agent`, or pass `--mock-agent <fixture>` / `--agent <real>`"), AGENT_ERR_NOT_GRANTED);
+		if (this.opts.mode === "mock") return this.mockCall(method, params);
+		return this.realCall(method, params);
+	}
+	mockCall(method, params) {
+		const shortName = method.startsWith("agent/") ? method.slice(6) : method;
+		const content = collectContent(params);
+		const matched = this.mocks.find((m) => m.ns === "agent" && m.method === shortName && (!m.match?.contentIncludes || content.includes(m.match.contentIncludes))) ?? this.mocks.find((m) => m.ns === "agent" && m.method === shortName);
+		if (matched && matched.result !== void 0) return matched.result;
+		if (shortName === "session.create") return {
+			app_session_uuid: `aps_mock_${Math.random().toString(16).slice(2, 10)}`,
+			expires_in: 600,
+			agent_submode: "auto",
+			granted_tools: []
+		};
+		if (shortName === "session.run") {
+			const text = String(params.content ?? "");
+			return {
+				run_id: "mock_run",
+				stream_id: "strm_mock",
+				frames: [{
+					event: "final",
+					text: `(mock) echoing: ${text}`,
+					seq: 0,
+					stream_id: "strm_mock"
+				}],
+				final: {
+					event: "final",
+					text: `(mock) echoing: ${text}`
+				},
+				frame_count: 1
+			};
+		}
+		if (shortName === "session.cancel") return { cancelled: true };
+		if (shortName === "session.history") return {
+			messages: [],
+			cursor: null
+		};
+		if (shortName === "session.delete") return { deleted: true };
+		if (shortName === "complete") return {
+			role: "assistant",
+			content: {
+				type: "text",
+				text: "(mock) no fixture matched"
+			},
+			model: "mock-model",
+			stopReason: "endTurn"
+		};
+		throw withCode(new Error(`unknown agent method: ${method}`), AGENT_ERR_INVALID_REQUEST);
+	}
+	requireAppSlug() {
+		if (!this.opts.appSlug) throw withCode(new Error("agent bridge has no app_slug — pass `--app-slug <slug>` so nexus can attribute the spend"), -32602);
+		return this.opts.appSlug;
+	}
+	async realCall(method, params) {
+		const shortName = method.startsWith("agent/") ? method.slice(6) : method;
+		switch (shortName) {
+			case "session.create": return this.sessionCreate(params);
+			case "session.run": return this.sessionRun(params);
+			case "session.cancel": return this.sessionCancel(params);
+			case "session.history": return this.sessionHistory(params);
+			case "session.delete": return this.sessionDelete(params);
+			case "complete": return this.complete(params);
+			default: throw withCode(new Error(`unknown agent method: ${method}`), AGENT_ERR_INVALID_REQUEST);
+		}
+	}
+	async sessionCreate(params) {
+		const acc = requireAccount(this.opts.account);
+		const submode = params.agent_submode ?? "auto";
+		if (submode !== "auto" && submode !== "fixed") throw withCode(new Error("agent_submode must be 'auto' or 'fixed'"), AGENT_ERR_INVALID_REQUEST);
+		const fixedClientId = params.fixed_client_id ?? params.fixedClientId ?? null;
+		if (submode === "fixed" && !fixedClientId) throw withCode(new Error("fixed_client_id required when agent_submode='fixed'"), AGENT_ERR_INVALID_REQUEST);
+		const minted = await mintAppSession(acc.host, {
+			pat: acc.pat,
+			kind: "agent",
+			app_slug: this.requireAppSlug(),
+			submode,
+			fixed_client_id: fixedClientId,
+			label: params.label ?? "anna-app executa dev",
+			quota_caps: params.quota_caps ?? null,
+			ttl_seconds: params.ttl_seconds ?? 600
+		});
+		this.sessions.set(minted.app_session_uuid, {
+			appSessionToken: minted.app_session_token,
+			appSessionUuid: minted.app_session_uuid,
+			expiresAt: Math.floor(Date.now() / 1e3) + (minted.expires_in || 600) - 30,
+			submode
+		});
+		return {
+			app_session_uuid: minted.app_session_uuid,
+			thread_id: minted.app_session_uuid,
+			agent_submode: submode,
+			fixed_client_id: fixedClientId,
+			expires_in: minted.expires_in,
+			granted_tools: []
+		};
+	}
+	getSession(params) {
+		const uuid = String(params.app_session_uuid ?? "");
+		if (!uuid.startsWith("aps_")) throw withCode(new Error("'app_session_uuid' must start with 'aps_'"), AGENT_ERR_INVALID_REQUEST);
+		const ms = this.sessions.get(uuid);
+		if (!ms) throw withCode(new Error(`app_session_uuid=${uuid} not in dev cache (expired or never created)`), AGENT_ERR_SESSION_NOT_FOUND);
+		if (ms.expiresAt < Math.floor(Date.now() / 1e3)) {
+			this.sessions.delete(uuid);
+			throw withCode(new Error(`app_session_uuid=${uuid} expired — call session.create again`), AGENT_ERR_SESSION_NOT_FOUND);
+		}
+		return ms;
+	}
+	async sessionRun(params) {
+		const acc = requireAccount(this.opts.account);
+		const ms = this.getSession(params);
+		const content = params.content;
+		if (typeof content !== "string" || !content.trim()) throw withCode(new Error("'content' must be a non-empty string"), AGENT_ERR_INVALID_REQUEST);
+		const runId = params.run_id ?? `run_${Math.random().toString(16).slice(2, 18)}`;
+		const streamId = `strm_${Math.random().toString(16).slice(2, 18)}`;
+		const body = {
+			app_session_uuid: ms.appSessionUuid,
+			content,
+			run_id: runId,
+			stream: true
+		};
+		if (params.attachments !== void 0) body.attachments = params.attachments;
+		if (params.recursion_limit !== void 0) body.recursion_limit = params.recursion_limit;
+		if (params.allowed_tools !== void 0) body.allowed_tools = params.allowed_tools;
+		if (params.system !== void 0) body.system = params.system;
+		const mp = params.modelPreferences ?? params.model_preferences;
+		if (mp !== void 0) body.model_preferences = mp;
+		const url = `${hostOf(acc)}/api/v1/copilot/app/agent`;
+		const res = await fetch(url, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				authorization: `Bearer ${ms.appSessionToken}`,
+				accept: "text/event-stream"
+			},
+			body: JSON.stringify(body)
+		});
+		if (!res.ok || !res.body) {
+			const text = await res.text().catch(() => "");
+			throw withCode(new Error(`agent/session.run failed: HTTP ${res.status}: ${text}`), AGENT_ERR_PROVIDER_ERROR);
+		}
+		const frames = [];
+		let final = null;
+		const textAcc = [];
+		const reader = res.body.getReader();
+		const decoder = new TextDecoder();
+		let buf = "";
+		while (true) {
+			const { value, done } = await reader.read();
+			if (done) break;
+			buf += decoder.decode(value, { stream: true });
+			let idx;
+			while ((idx = buf.indexOf("\n\n")) >= 0) {
+				const frameRaw = buf.slice(0, idx);
+				buf = buf.slice(idx + 2);
+				const payload = parseSseFrame(frameRaw);
+				if (payload && typeof payload === "object") {
+					const frame = payload;
+					if (frame.seq === void 0) frame.seq = frames.length;
+					if (frame.stream_id === void 0) frame.stream_id = streamId;
+					frames.push(frame);
+					if (frame.event === "delta" && typeof frame.text === "string") textAcc.push(frame.text);
+					else if (frame.event === "final") final = frame;
+					if (frames.length > MAX_FRAMES_PER_RUN) throw withCode(new Error(`agent run exceeded ${MAX_FRAMES_PER_RUN} frames`), AGENT_ERR_RUN_TOO_LARGE);
+				}
+			}
+		}
+		if (buf.trim().length > 0) {
+			const payload = parseSseFrame(buf);
+			if (payload && typeof payload === "object") {
+				const frame = payload;
+				if (frame.seq === void 0) frame.seq = frames.length;
+				if (frame.stream_id === void 0) frame.stream_id = streamId;
+				frames.push(frame);
+				if (frame.event === "final") final = frame;
+			}
+		}
+		if (final === null && textAcc.length > 0) {
+			final = {
+				event: "final",
+				text: textAcc.join(""),
+				stream_id: streamId,
+				seq: frames.length,
+				synthesized: true
+			};
+			frames.push(final);
+		}
+		return {
+			run_id: runId,
+			stream_id: streamId,
+			frames,
+			final,
+			frame_count: frames.length
+		};
+	}
+	async sessionCancel(params) {
+		const acc = requireAccount(this.opts.account);
+		const ms = this.getSession(params);
+		const runId = params.run_id;
+		if (typeof runId !== "string" || !runId.trim()) throw withCode(new Error("'run_id' required"), AGENT_ERR_INVALID_REQUEST);
+		const url = `${hostOf(acc)}/api/v1/copilot/app/agent/cancel`;
+		const res = await fetch(url, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				authorization: `Bearer ${ms.appSessionToken}`
+			},
+			body: JSON.stringify({
+				app_session_uuid: ms.appSessionUuid,
+				run_id: runId
+			})
+		});
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			throw withCode(new Error(`agent/session.cancel failed: HTTP ${res.status}: ${text}`), AGENT_ERR_PROVIDER_ERROR);
+		}
+		return await res.json().catch(() => ({}));
+	}
+	async sessionHistory(params) {
+		const acc = requireAccount(this.opts.account);
+		const ms = this.getSession(params);
+		const limit = Math.min(200, Math.max(1, Number(params.limit ?? 50)));
+		const cursor = params.cursor ?? null;
+		const url = new URL(`${hostOf(acc)}/api/v1/copilot/app/sessions/${encodeURIComponent(ms.appSessionUuid)}/history`);
+		url.searchParams.set("limit", String(limit));
+		if (cursor) url.searchParams.set("cursor", String(cursor));
+		const res = await fetch(url, {
+			method: "GET",
+			headers: { authorization: `Bearer ${ms.appSessionToken}` }
+		});
+		if (res.status === 404) return {
+			messages: [],
+			cursor: null
+		};
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			throw withCode(new Error(`agent/session.history failed: HTTP ${res.status}: ${text}`), AGENT_ERR_PROVIDER_ERROR);
+		}
+		return await res.json();
+	}
+	async sessionDelete(params) {
+		const acc = requireAccount(this.opts.account);
+		const uuid = String(params.app_session_uuid ?? "");
+		if (!uuid.startsWith("aps_")) throw withCode(new Error("'app_session_uuid' must start with 'aps_'"), AGENT_ERR_INVALID_REQUEST);
+		const ms = this.sessions.get(uuid);
+		this.sessions.delete(uuid);
+		if (!ms) return {
+			deleted: true,
+			app_session_uuid: uuid,
+			already_gone: true
+		};
+		const url = `${hostOf(acc)}/api/v1/copilot/app/sessions/${encodeURIComponent(uuid)}`;
+		const res = await fetch(url, {
+			method: "DELETE",
+			headers: { authorization: `Bearer ${ms.appSessionToken}` }
+		});
+		if (!res.ok && res.status !== 404) {
+			const text = await res.text().catch(() => "");
+			throw withCode(new Error(`agent/session.delete failed: HTTP ${res.status}: ${text}`), AGENT_ERR_PROVIDER_ERROR);
+		}
+		return {
+			deleted: true,
+			app_session_uuid: uuid
+		};
+	}
+	/**
+	* L1 `agent/complete` — single-turn completion convenience. Mints a
+	* transient kind=complete session, forwards to `/copilot/app/complete`,
+	* returns the assistant message.
+	*/
+	async complete(params) {
+		const acc = requireAccount(this.opts.account);
+		const messages = params.messages;
+		if (!Array.isArray(messages) || messages.length === 0) throw withCode(new Error("'messages' must be a non-empty array"), AGENT_ERR_INVALID_REQUEST);
+		const minted = await mintAppSession(acc.host, {
+			pat: acc.pat,
+			kind: "complete",
+			app_slug: this.requireAppSlug()
+		});
+		const body = { messages };
+		if (params.system) body.system = params.system;
+		if (params.max_tokens != null) body.max_tokens = params.max_tokens;
+		if (params.maxTokens != null) body.max_tokens = params.maxTokens;
+		if (params.temperature != null) body.temperature = params.temperature;
+		if (params.stop) body.stop = params.stop;
+		if (params.model_hint) body.model_hint = params.model_hint;
+		if (params.metadata) body.metadata = params.metadata;
+		const res = await fetch(`${hostOf(acc)}/api/v1/copilot/app/complete`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				authorization: `Bearer ${minted.app_session_token}`
+			},
+			body: JSON.stringify(body)
+		});
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			throw withCode(new Error(`agent/complete failed: HTTP ${res.status}: ${text}`), AGENT_ERR_PROVIDER_ERROR);
+		}
+		return await res.json();
+	}
+};
+function collectContent(params) {
+	const parts = [];
+	if (typeof params.content === "string") parts.push(params.content);
+	if (typeof params.system === "string") parts.push(params.system);
+	const msgs = params.messages;
+	if (Array.isArray(msgs)) for (const m of msgs) {
+		const c = m.content;
+		if (typeof c === "string") parts.push(c);
+		else if (c && typeof c === "object" && "text" in c) parts.push(String(c.text ?? ""));
+	}
+	return parts.join("\n");
+}
+function parseSseFrame(frame) {
+	const lines = frame.split(/\r?\n/);
+	const dataLines = [];
+	let eventName = null;
+	for (const raw of lines) {
+		if (!raw || raw.startsWith(":")) continue;
+		if (raw.startsWith("data:")) dataLines.push(raw.slice(5).trimStart());
+		else if (raw.startsWith("event:")) eventName = raw.slice(6).trim();
+	}
+	if (dataLines.length === 0) return null;
+	const data = dataLines.join("\n");
+	try {
+		const obj = JSON.parse(data);
+		if (eventName && obj && typeof obj === "object" && !("event" in obj)) return {
+			...obj,
+			event: eventName
+		};
+		return obj;
+	} catch {
+		return {
+			event: eventName ?? "raw",
+			text: data
+		};
+	}
+}
+
+//#endregion
+export { AgentBridge };

package/dist/{apps-CDe6Fjq2.js → apps-Bt9CT5Sl.js}

@@ -1,5 +1,5 @@
 import { getAccount } from "./credentials-BTv2IfUZ.js";
-import { listDevApps } from "./dev-app-cache-BMfOlTHd.js";
+import { listDevApps } from "./dev-app-cache-DAHcq46m.js";
 import { bold, cyan, dim, green, red, yellow } from "kleur/colors";
 
 //#region src/commands/apps.ts

package/dist/bridge-AJilXBw2.js

@@ -0,0 +1,3 @@
+import { PINNED_RUNTIME_VERSION, PythonBridge } from "./bridge-nqQ3-j-t.js";
+
+export { PINNED_RUNTIME_VERSION, PythonBridge };

package/dist/{bridge-BQUo6ehX.js → bridge-nqQ3-j-t.js}

@@ -9,7 +9,7 @@ import { createInterface } from "node:readline";
 * `uvx <pkg>@<version>` so end users always run the dispatcher version
 * the CLI was tested against.
 */
-const PINNED_RUNTIME_VERSION = "0.2.0a2";
+const PINNED_RUNTIME_VERSION = "0.2.0a3";
 var PythonBridge = class {
 	proc = null;
 	nextId = 1;

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { printMascot } from "./mascot-wlYTJqMs.js";
 import { dirname, extname, join, relative, resolve } from "node:path";
 import { createRequire } from "node:module";
 import { Command } from "commander";
@@ -53,6 +54,7 @@ function runInit(opts) {
 	}
 	const tplRoot = templateRoot(opts.template);
 	copyDirWithSubst(tplRoot, target, opts.slug);
+	printMascot(`scaffolded a fresh app — happy hacking!`);
 	console.log(kleur.green(`✓ scaffolded "${opts.slug}" at ${target}`));
 	console.log(kleur.gray(`  next: cd ${opts.targetDir} && anna-app validate`));
 	return 0;
@@ -423,6 +425,10 @@ function printResult(result) {
 const pkg = createRequire(import.meta.url)("../package.json");
 const program = new Command();
 program.name("anna-app").description("Anna App developer CLI (scaffold, validate, harness)").version(pkg.version);
+const argv = process.argv.slice(2);
+const wantsTopLevelHelp = argv.length === 0 || argv[0] === "-h" || argv[0] === "--help" || argv[0] === "help";
+const tagline = wantsTopLevelHelp ? `v${pkg.version} — run \`anna-app help <command>\` for details` : `v${pkg.version} — ${argv.join(" ")}`;
+printMascot(tagline);
 program.command("init <dir>").description("Scaffold a new Anna App project").option("--slug <slug>", "App slug (lowercase, hyphens)", "").option("--template <name>", "Template to use", "minimal").option("--force", "Overwrite existing dir if non-empty", false).action((dir, opts) => {
 	const slug = opts.slug || dir.split(/[\\/]/).pop() || "my-anna-app";
 	const code = runInit({
@@ -445,7 +451,7 @@ program.command("validate").description("Run schema + ACL checks on a manifest+b
 	process.exit(code);
 });
 program.command("dev").description("Run a local harness (in-process dispatcher + iframe + SSE relay)").option("--manifest <path>", "manifest.json path", "manifest.json").option("--bundle <dir>", "bundle directory (default: ./bundle)").option("--slug <slug>", "App slug (overrides manifest.slug/name)").option("--view <name>", "View name to open (default: manifest default)").option("--matrix-nexus-root <path>", "matrix-nexus checkout (auto-detected if omitted; can also use $ANNA_NEXUS_ROOT)").option("--port <number>", "HTTP port", "5180").option("--user-id <id>", "Harness user_id", "1").option("--cwd <dir>", "Project root (default: cwd)").option("--no-watch", "Disable bundle file watcher (default: enabled)").option("--executa <spec>", "Explicit executa registration; repeatable. Spec: comma-separated key=value (dir=<path>[,tool_id=<id>][,type=python|node|go|binary][,command=\"<argv>\"]). When only `dir=` is given, the executa is auto-detected from executa.json / pyproject.toml / package.json / go.mod. Overrides directory auto-discovery under <manifest-dir>/executas/.", (val, prev) => prev ? [...prev, val] : [val]).option("--no-llm", "Disable LLM bridge (anna.llm/agent return llm_disabled)").option("--mock-llm <fixture>", "Serve canned LLM responses from a JSONL fixture").option("--llm-account <host>", "Saved account host to use (default: current)").option("--llm-app-slug <slug>", "Override the manifest slug used to register / look up the dev AnnaApp (default: manifest.slug)").action(async (opts) => {
-	const { runDev, parseExecutaSpec } = await import("./dev-DoY58pBM.js");
+	const { runDev, parseExecutaSpec } = await import("./dev-BRlFgo2I.js");
 	const cwd = opts.cwd ?? process.cwd();
 	let executas;
 	if (opts.executa && opts.executa.length > 0) {
@@ -479,7 +485,7 @@ program.command("dev").description("Run a local harness (in-process dispatcher +
 });
 const fixture = program.command("fixture").description("Inspect / replay harness recordings (Phase 6)");
 fixture.command("verify <file>").description("Schema + invariant checks on a harness JSONL recording").option("--json", "Emit machine-readable JSON", false).action(async (file, opts) => {
-	const { runFixtureVerify } = await import("./fixture-BEu4LXLG.js");
+	const { runFixtureVerify } = await import("./fixture-CATHyLLI.js");
 	const code = await runFixtureVerify({
 		file,
 		json: opts.json
@@ -487,7 +493,7 @@ fixture.command("verify <file>").description("Schema + invariant checks on a har
 	process.exit(code);
 });
 fixture.command("summarize <file>").description("Print a human-readable digest of a harness recording").option("--json", "Emit machine-readable JSON", false).action(async (file, opts) => {
-	const { runFixtureSummarize } = await import("./fixture-BEu4LXLG.js");
+	const { runFixtureSummarize } = await import("./fixture-CATHyLLI.js");
 	const code = await runFixtureSummarize({
 		file,
 		json: opts.json
@@ -495,7 +501,7 @@ fixture.command("summarize <file>").description("Print a human-readable digest o
 	process.exit(code);
 });
 fixture.command("replay <file>").description("Dry-run replay of a harness recording (Phase 6 MVP)").option("--manifest <path>", "manifest.json path", "manifest.json").action(async (file, opts) => {
-	const { runFixtureReplay } = await import("./fixture-BEu4LXLG.js");
+	const { runFixtureReplay } = await import("./fixture-CATHyLLI.js");
 	const code = await runFixtureReplay({
 		file,
 		manifest: opts.manifest
@@ -503,12 +509,12 @@ fixture.command("replay <file>").description("Dry-run replay of a harness record
 	process.exit(code);
 });
 program.command("doctor").description("Check environment for `anna-app dev` (uv, matrix-nexus, dev key)").option("--matrix-nexus-root <path>", "matrix-nexus checkout (optional)").action(async (opts) => {
-	const { runDoctor } = await import("./doctor-DP2UB10l.js");
+	const { runDoctor } = await import("./doctor-C8MWfLt8.js");
 	const code = await runDoctor({ matrixNexusRoot: opts.matrixNexusRoot });
 	process.exit(code);
 });
 program.command("login").description("Device-flow login against a nexus host; saves a PAT to ~/.config/anna/credentials.json").requiredOption("--host <url>", "nexus base URL, e.g. https://nexus.example.com").option("--no-browser", "Do not open a browser window automatically", false).action(async (opts) => {
-	const { runLogin } = await import("./login-dl1Zfny8.js");
+	const { runLogin } = await import("./login-CsIVbrmf.js");
 	const code = await runLogin({
 		host: opts.host,
 		noBrowser: opts.browser === false
@@ -516,7 +522,7 @@ program.command("login").description("Device-flow login against a nexus host; sa
 	process.exit(code);
 });
 program.command("logout").description("Remove a saved PAT entry").option("--host <url>", "Account to remove (default: current)").option("--all", "Remove every saved account", false).action(async (opts) => {
-	const { runLogout } = await import("./logout-DablvlFs.js");
+	const { runLogout } = await import("./logout-gfmKQxMj.js");
 	const code = await runLogout({
 		host: opts.host,
 		all: opts.all
@@ -524,18 +530,81 @@ program.command("logout").description("Remove a saved PAT entry").option("--host
 	process.exit(code);
 });
 program.command("whoami").description("Show the current account (and any others)").option("--json", "Emit machine-readable JSON", false).action(async (opts) => {
-	const { runWhoami } = await import("./whoami-giXOY415.js");
+	const { runWhoami } = await import("./whoami-BS5wy-Nh.js");
 	const code = await runWhoami({ json: opts.json });
 	process.exit(code);
 });
 program.command("apps:list").description("List dev apps installed for the current PAT").option("--account <host>", "Saved account host (default: current)").option("--json", "Emit machine-readable JSON", false).action(async (opts) => {
-	const { runAppsList } = await import("./apps-CDe6Fjq2.js");
+	const { runAppsList } = await import("./apps-Bt9CT5Sl.js");
 	const code = await runAppsList({
 		account: opts.account,
 		json: opts.json
 	});
 	process.exit(code);
 });
+const executa = program.command("executa").description("Standalone Executa plugin scaffolding + local runner");
+executa.command("init <dir>").description("Scaffold a standalone Executa plugin (python | node | go)").option("--slug <slug>", "Plugin slug (lowercase, hyphens)", "").option("--template <name>", "Language template: python | node | go", "python").option("--tool-id <id>", "Override the minted tool_id (default: tool-dev-<slug>)").option("--force", "Overwrite existing dir if non-empty", false).action(async (dir, opts) => {
+	const slug = opts.slug || dir.split(/[\\/]/).pop() || "my-executa";
+	const tpl = opts.template;
+	if (![
+		"python",
+		"node",
+		"go"
+	].includes(tpl)) {
+		console.error(`✗ unknown template "${opts.template}" — expected python | node | go`);
+		process.exit(2);
+	}
+	const { runExecutaInit } = await import("./executa-init-COEmKDOE.js");
+	const code = runExecutaInit({
+		targetDir: dir,
+		slug,
+		template: tpl,
+		toolId: opts.toolId,
+		force: opts.force
+	});
+	process.exit(code);
+});
+executa.command("register").description("Register a standalone executa with nexus so `executa dev --storage real` (and future agent / sampling real-mode flows) can mint tokens for it").requiredOption("--tool-id <id>", "Executa tool_id (matches manifest.name)").option("--slug <slug>", "App slug (default: executa-<tool_id>; must be lowercase + hyphens)").option("--name <name>", "Human-readable display name (default: <tool_id>)").option("--account <host>", "Saved account host (default: current)").action(async (opts) => {
+	const { runExecutaRegister } = await import("./executa-register-66WKIwQQ.js");
+	const code = await runExecutaRegister(opts);
+	process.exit(code);
+});
+executa.command("dev").description("Run one Executa plugin in isolation (REPL or one-shot describe/invoke)").option("--dir <path>", "Executa project dir (default: CWD)").option("--spec <spec>", "Override discovery: comma-separated key=value (tool_id=...,type=...,command=\"...\")").option("--describe", "Print MANIFEST and exit", false).option("--health", "Print health and exit", false).option("--invoke <tool>", "Invoke one tool and exit").option("--args <json>", "JSON object passed as tool arguments", "{}").option("--json", "One-shot: emit compact JSON (no banners)", false).option("--no-sampling", "Hard-disable sampling reverse RPC (returns sampling_disabled)").option("--mock-sampling <fixture>", "Serve canned sampling responses from a JSONL fixture (offline)").option("--app-slug <slug>", "Forward sampling to nexus on behalf of this dev AnnaApp slug").option("--sampling-account <host>", "Saved account host for nexus sampling (default: current)").option("--no-agent", "Hard-disable agent reverse RPC (returns agent_not_granted)").option("--mock-agent <fixture>", "Serve canned agent/* responses from a JSONL fixture (offline)").option("--agent-account <host>", "Saved account host for nexus agent (default: --sampling-account or current)").option("--storage <mode>", "Storage backend: off | memory | mock | real (default: memory)").option("--mock-storage <fixture>", "Serve canned storage/* + files/* responses from a JSONL fixture").option("--storage-account <host>", "Saved account host for nexus storage (default: --sampling-account or current)").option("--storage-scopes <list>", "Comma-separated scopes for real storage tokens (default: user,app,tool)").option("--no-image", "Hard-disable image reverse RPC (returns image_not_granted)").option("--mock-image <fixture>", "Serve canned image/generate + image/edit responses from a JSONL fixture").option("--image-account <host>", "Saved account host for nexus image (default: --sampling-account or current)").option("--no-upload", "Hard-disable host/uploadFile reverse RPC (returns upload_not_granted)").option("--mock-upload <fixture>", "Serve canned host/uploadFile responses from a JSONL fixture").option("--upload-account <host>", "Saved account host for nexus uploads (default: --sampling-account or current)").action(async (opts) => {
+	const { runExecutaDev } = await import("./executa-dev-4FZ7AJHR.js");
+	const storageMode = opts.storage === void 0 ? void 0 : (() => {
+		const m = opts.storage;
+		if (m === "off" || m === "memory" || m === "mock" || m === "real") return m;
+		console.error(`✗ --storage must be one of off | memory | mock | real (got: ${m})`);
+		process.exit(2);
+	})();
+	const code = await runExecutaDev({
+		dir: opts.dir,
+		spec: opts.spec,
+		describe: opts.describe,
+		health: opts.health,
+		invoke: opts.invoke,
+		args: opts.args,
+		json: opts.json,
+		noSampling: opts.sampling === false,
+		mockSampling: opts.mockSampling,
+		appSlug: opts.appSlug,
+		samplingAccount: opts.samplingAccount,
+		noAgent: opts.agent === false,
+		mockAgent: opts.mockAgent,
+		agentAccount: opts.agentAccount,
+		storage: storageMode,
+		mockStorage: opts.mockStorage,
+		storageAccount: opts.storageAccount,
+		storageScopes: opts.storageScopes,
+		noImage: opts.image === false,
+		mockImage: opts.mockImage,
+		imageAccount: opts.imageAccount,
+		noUpload: opts.upload === false,
+		mockUpload: opts.mockUpload,
+		uploadAccount: opts.uploadAccount
+	});
+	process.exit(code);
+});
 program.parseAsync(process.argv).catch((e) => {
 	console.error(e);
 	process.exit(2);

package/dist/dev-BRlFgo2I.js

@@ -0,0 +1,3 @@
+import { parseExecutaSpec, runDev } from "./dev-C6v5yRV2.js";
+
+export { parseExecutaSpec, runDev };

package/dist/{dev-DoY58pBM.js → dev-C6v5yRV2.js}

@@ -31,8 +31,8 @@ async function runDev(opts) {
 	}
 	const matrixNexusRoot = await resolveMatrixNexusRoot(opts.matrixNexusRoot, cwd);
 	const mode = matrixNexusRoot ? "nexus-source" : "uvx";
-	const { PythonBridge, PINNED_RUNTIME_VERSION } = await import("./bridge-BEHyfpPI.js");
-	const { HarnessServer } = await import("./server-NXmiWJjX.js");
+	const { PythonBridge, PINNED_RUNTIME_VERSION } = await import("./bridge-AJilXBw2.js");
+	const { HarnessServer } = await import("./server-D8R6ppOp.js");
 	const bridge = new PythonBridge({
 		mode,
 		matrixNexusRoot: matrixNexusRoot ?? void 0,
@@ -122,8 +122,8 @@ async function runDev(opts) {
 * registered `appSlug`.
 */
 async function resolveRealLlm(args) {
-	const { getAccount } = await import("./credentials-CIOYq2Lm.js");
-	const { ensureDevAppRegistered } = await import("./dev-app-cache-cXvO2XwQ.js");
+	const { getAccount } = await import("./credentials-DDqx6XMQ.js");
+	const { ensureDevAppRegistered } = await import("./dev-app-cache-DGF2Kuzd.js");
 	const acc = getAccount(args.account);
 	if (!acc) {
 		console.error(red("✗ no developer PAT on disk — run `anna-app login --host <nexus-url>` first.\n  (or use `--no-llm` / `--mock-llm <fixture>` to develop offline.)"));

package/dist/dev-account-DCyjamBa.js

@@ -0,0 +1,44 @@
+import { canonicalHost, getAccount } from "./credentials-BTv2IfUZ.js";
+
+//#region src/executa/dev-account.ts
+/** Embed a JSON-RPC error code on a thrown Error so the runner can forward it. */
+function withCode(err, code) {
+	err.rpcCode = code;
+	return err;
+}
+/**
+* Resolve a saved developer PAT for the given account host (or the
+* "current" one when omitted).
+*
+* @throws JSON-RPC `-32001` when no PAT is on disk or it has expired.
+*/
+function requireAccount(account) {
+	const acc = getAccount(account);
+	if (!acc) throw withCode(new Error("no PAT on disk — run `anna-app login --host <nexus-url>` first (or use a `mock`/`off`/`memory` mode for the affected bridge)"), -32001);
+	if (acc.expires_at && acc.expires_at < Math.floor(Date.now() / 1e3)) throw withCode(new Error("PAT expired — run `anna-app login` again"), -32001);
+	return acc;
+}
+/** Return the canonical `https://host[:port]` form of a saved account. */
+function hostOf(acc) {
+	return canonicalHost(acc.host);
+}
+/**
+* Call `POST /api/v1/anna-apps/dev/session/mint` and parse the response.
+* Thin wrapper used by both sampling and agent bridges.
+*/
+async function mintAppSession(host, body) {
+	const url = `${canonicalHost(host)}/api/v1/anna-apps/dev/session/mint`;
+	const res = await fetch(url, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify(body)
+	});
+	if (!res.ok) {
+		const text = await res.text().catch(() => "");
+		throw withCode(new Error(`session.mint failed: HTTP ${res.status} ${text}`), -32e3);
+	}
+	return await res.json();
+}
+
+//#endregion
+export { hostOf, mintAppSession, requireAccount, withCode };