@stackbone/cli 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-08-10
+
+### Added
+
+- **`stackbone link` refuses a box the control plane could not work with, before
+  it writes anything.** The command registered whatever answered the URL, so a
+  container too old to be registered from the browser could still be linked from
+  the terminal without a word — and the failure surfaced later, on the first
+  screen that needed something the box does not speak, with a deployment row on
+  file to explain it. `link` now reads the box's public handshake
+  (`GET <url>/api/contract`, no credential) right after it resolves the agent and
+  before it verifies `--secret`, and refuses with the same sentence the browser
+  wizard prints. A box that never answers, one that answers with something that
+  is not a handshake, and one that is simply too old each fail in their own
+  words. Nothing is written on refusal: no deployment, no local project file.
+
+### Changed
+
+- **The agent protocol the box reports goes from 14 to 15, `stackbone dev`
+  included.** The box now permits the `stackbone-signature` request header on a
+  cross-origin preflight, which is what lets a browser sign a challenge against
+  it. Nothing on the wire changes shape and no capability moves — the number is
+  the change, and it is what a caller reads to know the box has it. The origin
+  allowlist is untouched: one more permitted header is not one more permitted
+  origin.
+- **`stackbone package` says how a managed Redis URL is written.** The generated
+  `.env` and README carried `redis://host:6379`, which no managed provider
+  accepts: they all hand out a password, some require TLS, and a password
+  containing `/`, `+`, `=` or `@` has to be percent-encoded or the URL does not
+  parse. All three are now spelled out where the operator reads them, next to the
+  note that the agent PINGs Redis before starting and stops with the reason if it
+  cannot.
+
 ## [0.3.1] - 2026-08-06
 
 ### Added

package/main.js

@@ -501,6 +501,25 @@ var init_approvals = __esmMin((() => {
 //#endregion
 //#region ../../libs/shared/validators/src/lib/agents/contract.ts
 /**
+* Whether a box speaking protocol `version` can be registered as a deployment.
+* Pure and total: the caller passes the number the handshake reported.
+*/
+function supportsDeploymentRegistration(version) {
+	return version >= 15;
+}
+/**
+* The one sentence both doors print when a box is below the floor.
+*
+* Shared, not copied, because the wizard and `stackbone link` refuse by the same
+* rule and an operator who tries the other door must not read a different story.
+* For the same reason it names no door: there is no "register it from the
+* terminal instead" any more, and the only way out it can honestly offer is the
+* one that works everywhere — run a current image.
+*/
+function deploymentRegistrationRefusal(version) {
+	return `This box speaks protocol version ${version}. Registering a deployment needs version 15 or later, because an older box refuses the signed call that proves its secret. Update the image the box runs to a current one and try again.`;
+}
+/**
 * Validates that the negotiated `contract.version` is at or above the
 * version the SDK still executes against. Pure, table-driven, never throws.
 *
@@ -604,7 +623,7 @@ var init_deployments = __esmMin((() => {
 		agentSlug: agentSlugSchema,
 		url: z.url(),
 		hmacSecret: z.string().min(1),
-		imageTag: z.string().min(1).max(200)
+		imageTag: z.string().min(1).max(200).optional()
 	});
 	z.object({ url: z.url() });
 	deploymentResponseSchema = z.object({
@@ -3461,7 +3480,7 @@ function createContractStore(resolved = resolveConfig({})) {
 	};
 }
 async function performHandshake(baseUrl, fetchImpl) {
-	const url = `${baseUrl}${CONTRACT_PATH}`;
+	const url = `${baseUrl}${CONTRACT_PATH$1}`;
 	let response;
 	try {
 		response = await fetchImpl(url, { method: "GET" });
@@ -3547,12 +3566,12 @@ function maybeLogDebug(debugLogged, key, contract) {
 	debugLogged.add(key);
 	console.warn(`[stackbone] contract handshake ok: baseUrl=${key} version=${contract.version} capabilities=${contract.capabilities.length}`);
 }
-var CONTRACT_PATH;
+var CONTRACT_PATH$1;
 var init_contract_handshake = __esmMin((() => {
 	init_src$13();
 	init_config$1();
 	init_result$1();
-	CONTRACT_PATH = "/api/contract";
+	CONTRACT_PATH$1 = "/api/contract";
 }));
 //#endregion
 //#region ../../libs/sdk/src/contract/capability-registry.ts
@@ -10576,7 +10595,7 @@ var createBoxAuthGate = (options) => {
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/server/contract.ts
 init_src$13();
-var STACKBONE_CLI_BUILD_VERSION = "0.3.1";
+var STACKBONE_CLI_BUILD_VERSION = "0.3.2";
 /**
 * Capabilities the local emulator advertises on `GET /api/contract`, derived
 * from the route registry above so the advertised set and the mounted routes
@@ -10597,7 +10616,7 @@ var EMULATOR_CAPABILITIES = Object.keys({
 	"browser.provider": "/api/browser-provider"
 });
 var buildContractResponse = () => contractResponseSchema.parse({
-	version: 14,
+	version: 15,
 	minSupported: 1,
 	capabilities: [...EMULATOR_CAPABILITIES],
 	build: {
@@ -40738,8 +40757,7 @@ var redisConnection = (redisUrl) => {
 	const db = path === "" ? void 0 : Number(path);
 	if (db !== void 0 && !Number.isInteger(db)) throw new Error(`Invalid Redis database in URL path: '${url.pathname}' (expected an integer)`);
 	return {
-		host: url.hostname,
-		port: url.port ? Number(url.port) : 6379,
+		url: redisUrl,
 		...db === void 0 ? {} : { db },
 		maxRetriesPerRequest: null
 	};
@@ -41160,7 +41178,7 @@ var init_connections = __esmMin((() => {
 	buildAgentEnv = (base, injection, options) => {
 		const env = {
 			...base,
-			[STACKBONE_ENV_KEYS.contractVersion]: String(14),
+			[STACKBONE_ENV_KEYS.contractVersion]: String(15),
 			[STACKBONE_ENV_KEYS.agentId]: injection.agentId,
 			[STACKBONE_ENV_KEYS.postgresUrl]: injection.services.postgresUrl,
 			[STACKBONE_ENV_KEYS.s3Endpoint]: injection.services.s3Endpoint,
@@ -45043,7 +45061,8 @@ var buildEmulatorApp = (opts, hooks = {}) => {
 			"x-stackbone-session",
 			"x-stackbone-conversation",
 			"x-api-key",
-			"anthropic-version"
+			"anthropic-version",
+			STACKBONE_SIGNATURE_HEADER
 		],
 		exposeHeaders: ["X-Stackbone-Run-Id"]
 	}));
@@ -49159,7 +49178,9 @@ STACKBONE_SECRET_KEY=${secretKey}
 # agent creates its own schema on first boot. It must have the pgvector extension
 # available — see the README.
 # DATABASE_URL=postgres://user:password@host:5432/dbname?sslmode=require
-# WORKFLOW_REDIS_URL=redis://host:6379
+# WORKFLOW_REDIS_URL=redis://default:password@host:6379
+# Managed Redis always wants a password, and some require TLS — use rediss:// for
+# those. Percent-encode a password containing / + = or @, or the URL will not parse.
 
 # ---- Optional ----------------------------------------------------------------
 # Set if your database role is not allowed to create schemas; you then apply the
@@ -49244,6 +49265,14 @@ and apply these by hand first, in filename order:
 
 Both live inside the image; \`docker run --rm ${input.imageTag} ls <path>\` lists them.
 
+Redis needs no preparation, only a reachable URL. Managed instances hand out a
+password, so the URL carries one — \`redis://default:password@host:6379\`. Use
+\`rediss://\` where the provider requires TLS (Upstash, ElastiCache with encryption
+in transit), and percent-encode a password containing \`/\`, \`+\`, \`=\` or \`@\`. The
+agent PINGs Redis before it starts and stops with the reason if it cannot: a
+rejected password fails right away, and a Redis still starting up is retried for
+30 seconds first.
+
 ## Running it somewhere other than Compose
 
 The agent serves on port **${RUNTIME_PORT}** by default, and binds whatever
@@ -54060,7 +54089,7 @@ var buildHandler$2 = (ctx, flags) => protectedCommand(async (innerCtx) => {
 			tunnelUrl: session.publicUrl,
 			localUrl: session.emulatorUrl,
 			deeplink,
-			contractVersion: 14,
+			contractVersion: 15,
 			capabilityCount: EMULATOR_CAPABILITIES.length,
 			agentName: agent.name,
 			colors: process.stdout.isTTY === true
@@ -63362,6 +63391,84 @@ var verifyDeploymentSecret = async (args) => {
 	return readIdentityVerification(response);
 };
 //#endregion
+//#region src/services/handshake.service.ts
+init_src$13();
+/** Public, credential-free handshake every deployed box serves. */
+var CONTRACT_PATH = "/api/contract";
+/**
+* Something is at that address, but it is not a Stackbone box: a gateway's error
+* page, a company site, a load balancer in front of the wrong service. Kept
+* distinct from "nothing answered" because the remedy is different — one is an
+* address to correct, the other a machine to go and look at.
+*/
+var notAHandshake = (url, status, cause) => new StackboneCliError({
+	code: "generic",
+	message: `${url} answered with HTTP ${status}, but not with a Stackbone box handshake`,
+	suggestion: "Check --url points at the box itself: a company site, or a load balancer in front of the wrong service, answers just like this.",
+	cause
+});
+/**
+* Asks a box which protocol version it speaks, before it is registered.
+*
+* Uses a DIRECT `fetch` — `ctx.http` refuses absolute URLs on purpose (it only
+* ever talks to the control plane), and this is a cross-host call to the
+* customer's own box. The handshake is public and takes no credential, which is
+* what makes it usable here: at this point in `link` nothing has been registered,
+* so there is no identity to present anyway.
+*/
+var readBoxContract = async (args) => {
+	const fetchImpl = args.fetchImpl ?? fetch;
+	let contractUrl;
+	try {
+		contractUrl = new URL(CONTRACT_PATH, args.url).toString();
+	} catch (cause) {
+		throw new StackboneCliError({
+			code: "generic",
+			message: `--url is not a valid URL: ${args.url}`,
+			suggestion: "Pass the full public URL of the deployed agent, e.g. https://agent.example.com",
+			cause
+		});
+	}
+	let response;
+	try {
+		response = await fetchImpl(contractUrl, { method: "GET" });
+	} catch (cause) {
+		throw new StackboneCliError({
+			code: "generic",
+			message: `Nothing answered at ${args.url}, so there is no way to read which protocol version that box speaks`,
+			suggestion: "Check --url is the public address of the running container and that this machine can reach it.",
+			cause
+		});
+	}
+	let body;
+	try {
+		body = await response.json();
+	} catch (cause) {
+		throw notAHandshake(args.url, response.status, cause);
+	}
+	const parsed = contractResponseSchema.safeParse(body);
+	if (!response.ok || !parsed.success) throw notAHandshake(args.url, response.status, parsed.success ? body : parsed.error);
+	return parsed.data;
+};
+/**
+* Refuses a box this product cannot register, whatever door it came through.
+*
+* Pure and total: it reads the version the handshake reported and nothing else.
+* The floor is `MIN_SUPPORTED_DEPLOYMENT_REGISTRATION_CONTRACT_VERSION`, NOT the
+* SDK-wide `MIN_SUPPORTED_CONTRACT_VERSION` — that one is 1, the handshake schema
+* already refuses anything below 1, and a guard built on it could never fire.
+* The sentence comes from the shared source the browser wizard prints too, so an
+* operator who tries the other door reads the same story about the same box.
+*/
+var assertBoxCanBeRegistered = (contract) => {
+	if (supportsDeploymentRegistration(contract.version)) return;
+	throw new StackboneCliError({
+		code: "generic",
+		message: deploymentRegistrationRefusal(contract.version),
+		suggestion: "Re-run `stackbone link` once the box is running a current image."
+	});
+};
+//#endregion
 //#region src/commands/link/link.command.ts
 var requireLinkField = (value, flag, description) => {
 	const trimmed = (value ?? "").trim();
@@ -63448,6 +63555,8 @@ var runLink = async (ctx, args) => {
 	const activeOrg = await getActiveOrganization(ctx);
 	const agent = await getAgentByOwnerAndSlug(ctx, activeOrg.slug, chosenSlug);
 	if (!ctx.flags.json) log.step(`Linking ${targetDir} to ${agent.slug}`);
+	if (!ctx.flags.json) log.step("Reading the box protocol version");
+	assertBoxCanBeRegistered(await readBoxContract({ url }));
 	if (!ctx.flags.json) log.step("Verifying the --secret against the deployed container");
 	const identityVerification = await verifyDeploymentSecret({
 		url,
@@ -65746,7 +65855,7 @@ if (shouldReexecUnderWinpty({
 if (isVersionFlag(rawArgs)) {
 	process.stdout.write(`${formatVersionOutput({
 		cliVersion: STACKBONE_CLI_BUILD_VERSION,
-		contractVersion: 14
+		contractVersion: 15
 	})}\n`);
 	process.exit(0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbone/cli",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {