deepspace 0.28.0 → 0.28.2

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/cli/cli.ts
 import {
-  defineCommand as defineCommand14,
+  defineCommand as defineCommand15,
   runMain,
   runCommand,
   renderUsage
@@ -660,6 +660,9 @@ var INVALID_URLS = {
   platform: "http://127.0.0.1:9",
   deploy: "http://127.0.0.1:9"
 };
+function appDomainForEnv(env) {
+  return env === "production" ? "app.space" : env === "staging" ? "spacestest.com" : null;
+}
 var PLATFORM_URLS = DEEPSPACE_ENV === "production" ? PROD_URLS : DEEPSPACE_ENV === "staging" ? STAGING_URLS : INVALID_URLS;
 var PLANE_AUTH_URLS = {
   production: PROD_URLS.auth,
@@ -689,10 +692,11 @@ function decodeJwtPayload(token) {
   return JSON.parse(Buffer.from(payloadSegment, "base64url").toString("utf8"));
 }
 
-// src/cli/session.ts
+// src/shared/auth-session.ts
 var SESSION_COOKIE = "__Secure-better-auth.session_token";
-async function exchangeSession(authUrl, sessionToken) {
-  const path = "/api/auth/token";
+
+// src/cli/session.ts
+async function exchangeSessionToken(authUrl, sessionToken, path, action, body) {
   let res;
   try {
     res = await fetchWithTransientRetry(
@@ -701,8 +705,10 @@ async function exchangeSession(authUrl, sessionToken) {
         method: "POST",
         headers: {
           Cookie: `${SESSION_COOKIE}=${encodeURIComponent(sessionToken)}`,
-          Origin: authUrl
-        }
+          Origin: authUrl,
+          ...body === void 0 ? {} : { "Content-Type": "application/json" }
+        },
+        body
       }),
       { timeoutMs: 15e3 }
     );
@@ -717,7 +723,7 @@ async function exchangeSession(authUrl, sessionToken) {
   if (res.status === 401) return null;
   if (!res.ok) {
     throw new ApiError(
-      `The auth service could not refresh the CLI token (HTTP ${res.status}). Retry without logging in again.`,
+      `The auth service could not ${action} (HTTP ${res.status}). Retry without logging in again.`,
       res.status,
       res.status === 429 ? "rate_limited" : "auth_service_unavailable",
       path
@@ -744,6 +750,18 @@ async function exchangeSession(authUrl, sessionToken) {
   }
   return data.token;
 }
+function exchangeSession(authUrl, sessionToken) {
+  return exchangeSessionToken(authUrl, sessionToken, "/api/auth/token", "refresh the CLI token");
+}
+function exchangeAgentSession(authUrl, sessionToken, target2) {
+  return exchangeSessionToken(
+    authUrl,
+    sessionToken,
+    "/api/auth/agent-token",
+    "mint the app-specific agent token",
+    JSON.stringify({ target: target2 })
+  );
+}
 
 // src/cli/lib/secure-file.ts
 import { chmodSync, writeFileSync } from "fs";
@@ -814,6 +832,14 @@ function isTokenValid(jwt, minimumValidityMs) {
 async function refreshTokenFromSession() {
   return await exchangeStoredSession();
 }
+async function mintAgentToken(target2) {
+  if (!existsSync(SESSION_PATH)) throw notAuthenticated("Not logged in");
+  const sessionToken = readFileSync2(SESSION_PATH, "utf-8").trim();
+  const token = await exchangeAgentSession(AUTH_URL, sessionToken, target2);
+  if (!token)
+    throw notAuthenticated("The stored session is no longer valid (expired or unreadable)");
+  return token;
+}
 async function exchangeStoredSession() {
   if (!existsSync(SESSION_PATH)) return null;
   const sessionToken = readFileSync2(SESSION_PATH, "utf-8").trim();
@@ -1774,6 +1800,24 @@ function healBlocker(appDir, wranglerEnv) {
   }
   return null;
 }
+async function registerForLocalRun(appDir, token, wranglerEnv) {
+  try {
+    return (await ensureAppRegistered(appDir, token, wranglerEnv))?.appId ?? null;
+  } catch (registrationError) {
+    let hasUsableId = false;
+    try {
+      hasUsableId = readAppId(appDir, wranglerEnv) !== null;
+    } catch {
+    }
+    if (!hasUsableId) throw registrationError;
+    const firstLine = registrationError instanceof Error ? registrationError.message.split("\n")[0] : String(registrationError);
+    process.stderr.write(
+      `warning: could not register the app (${firstLine}) \u2014 continuing without app secrets.
+`
+    );
+    return null;
+  }
+}
 function healRefusal(appDir, wranglerEnv) {
   const blocker = healBlocker(appDir, wranglerEnv);
   if (blocker === "placeholder_committed") {
@@ -2306,7 +2350,7 @@ function resolveWorkspaceWorktree(worktrees, workspaceId) {
 // src/cli/lib/source-api.ts
 function githubSourceRefusal(appId, repository) {
   return new Refusal(
-    `This app uses GitHub source (${repository}). Use normal Git/GitHub for source operations (clone, fetch, push); \`deepspace deploy\` ships the local working tree without changing Git.`,
+    `This app uses GitHub source (${repository}). Use normal Git/GitHub for source operations. \`deepspace deploy\` ships the local working tree without changing Git.`,
     "source_managed_by_github",
     { extra: { appId, repository } }
   );
@@ -3750,7 +3794,11 @@ async function ensurePortFree(port, host, waitMs = 15e3) {
     `Port ${port} is already in use.
 Free it with \`${killArgv.join(" ")}\`, or use another port: \`--port <other>\`.`,
     "port_in_use",
-    { extra: { port } }
+    // The machine action the contract documents for this refusal — the prose
+    // named it while `--json` carried none (2026-08-28 coldstart AX). Not
+    // actionRequired: freeing the port and choosing another port are both
+    // legitimate, so the choice stays the caller's.
+    { extra: { port }, action: { cwd: process.cwd(), argv: killArgv } }
   );
 }
 async function isHttpResponding(port, timeoutMs = 2e3) {
@@ -3892,6 +3940,7 @@ var dev_default = defineDeepspaceCommand({
     writeLaunchConfigIfMissing(appDir, detectAppName(appDir) ?? basename2(appDir), port, {
       updatePort: explicitPort
     });
+    ensureInstallReady(appDir);
     let token;
     try {
       token = await ensureToken();
@@ -3914,21 +3963,12 @@ var dev_default = defineDeepspaceCommand({
     if (wranglerEnv) say(`Wrangler env: ${wranglerEnv}`);
     say(`Port: ${port}`);
     if (host !== DEFAULT_DEV_HOST) say(`Host: ${host}`);
-    ensureInstallReady(appDir);
     const lintFindings = await lintProjectSchemas(appDir);
     if (lintFindings && lintFindings.length > 0 && !args.json) {
       for (const line of formatSchemaLintFindings(lintFindings)) console.warn(line);
     }
     let generatedSecretsCache;
-    let appIdForSecrets = null;
-    try {
-      appIdForSecrets = (await ensureAppRegistered(appDir, token, wranglerEnv))?.appId ?? null;
-    } catch (registrationError) {
-      process.stderr.write(
-        `warning: could not register the app (${registrationError instanceof Error ? registrationError.message.split("\n")[0] : String(registrationError)}) \u2014 continuing without app secrets.
-`
-      );
-    }
+    const appIdForSecrets = await registerForLocalRun(appDir, token, wranglerEnv);
     if (appIdForSecrets) {
       try {
         const refreshed = await refreshSecretsCache(DEPLOY_URL2, token, appIdForSecrets, wranglerEnv);
@@ -4436,7 +4476,6 @@ function saveTestAccountStore(store) {
 }
 
 // src/cli/lib/test-account-service.ts
-var SESSION_COOKIE2 = "__Secure-better-auth.session_token";
 var TestAccountServiceError = class extends Error {
   constructor(message, code) {
     super(message);
@@ -4449,7 +4488,7 @@ function serviceError(data, fallback) {
 var AUTH_URL4 = process.env.DEEPSPACE_AUTH_URL ?? PLATFORM_URLS.auth;
 function sessionCookie() {
   const token = readFileSync12(SESSION_PATH, "utf-8").trim();
-  return `${SESSION_COOKIE2}=${encodeURIComponent(token)}`;
+  return `${SESSION_COOKIE}=${encodeURIComponent(token)}`;
 }
 async function fetchRemoteTestAccounts() {
   const response = await fetch(`${AUTH_URL4}/api/auth/test-accounts`, {
@@ -4619,6 +4658,7 @@ var test_default = defineDeepspaceCommand({
       arg: args.port,
       worktree: () => resolveWorktreePort(appDir)
     });
+    ensureInstallReady(appDir);
     if (suite !== "unit") await ensurePortFree(port, "0.0.0.0");
     let token;
     let ownerId;
@@ -4633,17 +4673,8 @@ var test_default = defineDeepspaceCommand({
         { action: cliAction("deepspace", "auth", "login") }
       );
     }
-    ensureInstallReady(appDir);
     let generatedSecretsCache;
-    let appIdForSecrets = null;
-    try {
-      appIdForSecrets = (await ensureAppRegistered(appDir, token, wranglerEnv))?.appId ?? null;
-    } catch (registrationError) {
-      process.stderr.write(
-        `warning: could not register the app (${registrationError instanceof Error ? registrationError.message.split("\n")[0] : String(registrationError)}) \u2014 continuing without app secrets.
-`
-      );
-    }
+    const appIdForSecrets = await registerForLocalRun(appDir, token, wranglerEnv);
     if (appIdForSecrets) {
       try {
         const refreshed = await refreshSecretsCache(DEPLOY_URL3, token, appIdForSecrets, wranglerEnv);
@@ -4903,7 +4934,8 @@ async function requireConsent(opts) {
 
 // src/cli/commands/test-accounts.ts
 function testAccountFailure(err, fallbackCode) {
-  const message = err instanceof Error ? err.message : String(err);
+  const raw = err instanceof Error ? err.message : String(err);
+  const message = raw.replace(/\.\s*$/, "");
   const code = err instanceof TestAccountServiceError ? err.code : void 0;
   if (code === "test_account_cap") {
     return new Refusal(
@@ -4923,7 +4955,7 @@ function testAccountFailure(err, fallbackCode) {
       "not_authenticated"
     );
   }
-  return new Refusal(`Failed: ${message}`, code ?? fallbackCode);
+  return new Refusal(`Failed: ${raw}`, code ?? fallbackCode);
 }
 var create = defineDeepspaceCommand({
   meta: {
@@ -5266,7 +5298,7 @@ var recover = defineDeepspaceCommand({
       targets = remote.filter((account) => !known.has(account.id));
       if (targets.length === 0) {
         if (!args.json) console.log("Every pool account already has a local credential.");
-        return { data: { recovered: [], alreadyLocal: remote.length } };
+        return { data: { recovered: [], alreadyLocal: remote.length, savedTo: TEST_ACCOUNTS_PATH } };
       }
     } else {
       const match = args.id ? remote.find((account) => account.id === args.id) : remote.find((account) => account.email === args.email);
@@ -5317,7 +5349,7 @@ Stored in ${TEST_ACCOUNTS_PATH}. ${rotatedCount} account(s) had no stored creden
 Stored in ${TEST_ACCOUNTS_PATH}. Passwords were retrieved, not reset \u2014 other machines' credentials still work.`
       );
     }
-    return { data: { recovered, requested: targets.length, failures: [] } };
+    return { data: { recovered, requested: targets.length, failures: [], savedTo: TEST_ACCOUNTS_PATH } };
   }
 });
 var test_accounts_default = defineCommand2({
@@ -8030,6 +8062,9 @@ var whoami_default = defineDeepspaceCommand({
       console.log(`Email:      ${payload.email ?? "(none)"}`);
       console.log(`Type:       ${accountType}`);
       if (payload.iss) console.log(`Issuer:     ${payload.iss}`);
+      if (payload.exp) {
+        console.log(`Expires:    ${new Date(payload.exp * 1e3).toISOString()} (renews on use)`);
+      }
       console.log(`Dashboard:  ${DASHBOARD_URL}`);
       if (isTestAccount) {
         console.log("");
@@ -8512,7 +8547,7 @@ function renderSummary(summary) {
 var usage_default = defineDeepspaceCommand({
   meta: {
     name: "usage",
-    description: "Show account-wide credits and integration spend (all apps)"
+    description: "Show account-wide credits and integration spend (all apps). Storage is per app: `deepspace app files list`"
   },
   async run({ args }) {
     const token = await ensureToken();
@@ -10975,6 +11010,412 @@ var integrations_default = defineCommand9({
   }
 });
 
+// src/cli/commands/agent.ts
+import { createReadStream } from "fs";
+import { defineCommand as defineCommand10 } from "citty";
+
+// src/server/agent-target.ts
+var PRODUCTION_OFFICIAL_AGENT_ORIGINS = ["https://admin.deep.space"];
+var PRODUCTION_APP_DOMAIN = "app.space";
+function normalizeAgentTargetOrigin(value, policy) {
+  if (typeof value !== "string" || !value) return null;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  if (url.username || url.password || url.search || url.hash || url.pathname !== "/") return null;
+  const hostname = url.hostname.toLowerCase();
+  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(hostname);
+  if (loopback) {
+    return policy.allowLoopback && ["http:", "https:"].includes(url.protocol) ? url.origin : null;
+  }
+  if (url.protocol !== "https:" || url.port) return null;
+  if (policy.appDomain.toLowerCase() === PRODUCTION_APP_DOMAIN && PRODUCTION_OFFICIAL_AGENT_ORIGINS.includes(url.origin)) {
+    return url.origin;
+  }
+  const suffix = `.${policy.appDomain.toLowerCase()}`;
+  if (!hostname.endsWith(suffix)) return null;
+  const label = hostname.slice(0, -suffix.length);
+  return !label.includes(".") && validateAppName(label).valid ? url.origin : null;
+}
+
+// src/shared/bounded-body.ts
+var BodyTooLargeError = class extends Error {
+  constructor(maxBytes) {
+    super(`Body exceeds ${maxBytes} bytes`);
+    this.maxBytes = maxBytes;
+    this.name = "BodyTooLargeError";
+  }
+};
+async function readBoundedBodyText(source, maxBytes) {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+    throw new TypeError("maxBytes must be a positive safe integer");
+  }
+  const declared = source.headers.get("content-length");
+  if (declared && /^\d+$/.test(declared.trim()) && Number(declared) > maxBytes) {
+    await source.body?.cancel().catch(() => void 0);
+    throw new BodyTooLargeError(maxBytes);
+  }
+  if (!source.body) return "";
+  const reader = source.body.getReader();
+  const decoder = new TextDecoder();
+  let bytes = 0;
+  let text2 = "";
+  try {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      bytes += chunk.value.byteLength;
+      if (bytes > maxBytes) {
+        await reader.cancel().catch(() => void 0);
+        throw new BodyTooLargeError(maxBytes);
+      }
+      text2 += decoder.decode(chunk.value, { stream: true });
+    }
+    return text2 + decoder.decode();
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/shared/agent-tool-protocol.ts
+var AGENT_TOOL_REQUEST_BODY_CAP = 64 * 1024;
+var AGENT_TOOL_RESPONSE_BODY_CAP = 1024 * 1024;
+
+// src/cli/commands/agent.ts
+var DEFAULT_TIMEOUT_MS2 = 12e4;
+var MAX_TIMEOUT_MS = 6e5;
+var MAX_INPUT_BYTES = AGENT_TOOL_REQUEST_BODY_CAP;
+var MAX_RESPONSE_BYTES = AGENT_TOOL_RESPONSE_BODY_CAP;
+function badApp(message) {
+  throw new Refusal(message, "invalid_agent_app");
+}
+function isCanonicalAppLabel(value) {
+  return value.length >= APP_NAME_RULES.minLength && value.length <= APP_NAME_RULES.maxLength && APP_NAME_RULES.pattern.test(value);
+}
+function resolveAgentTarget(app2, plane = DEEPSPACE_ENV) {
+  if (typeof app2 !== "string" || !app2)
+    badApp("App must be a canonical app name or canonical app URL.");
+  const appDomain = appDomainForEnv(plane);
+  if (!appDomain) badApp("The selected DeepSpace environment is invalid.");
+  if (app2.toLowerCase() === "localhost") {
+    badApp("Pass an explicit loopback URL for local development (e.g. 'http://localhost:8787').");
+  }
+  if (isCanonicalAppLabel(app2)) {
+    return { url: `https://${app2}.${appDomain}` };
+  }
+  const url = normalizeAgentTargetOrigin(app2, {
+    appDomain,
+    allowLoopback: true
+  });
+  if (!url) {
+    badApp(
+      "App URL must be an exact canonical app origin (or a root loopback URL for local development)."
+    );
+  }
+  return { url };
+}
+function parseAgentTimeout(raw) {
+  if (raw == null) return DEFAULT_TIMEOUT_MS2;
+  const value = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isInteger(value) || value <= 0 || value > MAX_TIMEOUT_MS) {
+    throw new Refusal(
+      `Invalid --timeout '${String(raw)}'. Must be a positive integer up to ${MAX_TIMEOUT_MS} milliseconds.`,
+      "invalid_timeout"
+    );
+  }
+  return value;
+}
+function assertInputSize(value) {
+  if (Buffer.byteLength(value) > MAX_INPUT_BYTES) {
+    throw new Refusal(`Input exceeds the ${MAX_INPUT_BYTES}-byte limit.`, "input_too_large");
+  }
+}
+function serializeAgentInput(input) {
+  const body = JSON.stringify({ input });
+  if (Buffer.byteLength(body) > AGENT_TOOL_REQUEST_BODY_CAP) {
+    throw new Refusal(
+      `Tool request exceeds the ${AGENT_TOOL_REQUEST_BODY_CAP}-byte limit.`,
+      "input_too_large"
+    );
+  }
+  return body;
+}
+async function readBoundedLocalInput(source) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of source) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.length;
+    if (size > MAX_INPUT_BYTES) {
+      throw new Refusal(`Input exceeds the ${MAX_INPUT_BYTES}-byte limit.`, "input_too_large");
+    }
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function resolveAgentInput(opts) {
+  if (opts.input != null && opts.inputFile != null) {
+    throw new Refusal("Pass either --input or --input-file, not both.", "conflicting_input_args");
+  }
+  let raw = "{}";
+  if (opts.input != null) {
+    raw = opts.input;
+    assertInputSize(raw);
+  } else if (opts.inputFile != null) {
+    if (opts.inputFile === "-") {
+      raw = await readBoundedLocalInput(process.stdin);
+    } else {
+      try {
+        raw = await readBoundedLocalInput(createReadStream(opts.inputFile));
+      } catch (error) {
+        if (error instanceof Refusal) throw error;
+        throw new Refusal(`Could not read input file '${opts.inputFile}'.`, "input_file_unreadable");
+      }
+    }
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new Refusal("Input is not valid JSON.", "invalid_input_json");
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validApp(value) {
+  return isRecord(value) && typeof value.id === "string" && typeof value.name === "string";
+}
+function validTool(value) {
+  return isRecord(value) && typeof value.name === "string" && typeof value.description === "string" && Object.prototype.hasOwnProperty.call(value, "inputSchema");
+}
+function parseToolsResponse(value) {
+  if (!isRecord(value) || value.ok !== true || !validApp(value.app) || !Array.isArray(value.tools)) {
+    throw new Refusal("The app returned an unexpected tools response.", "invalid_agent_response");
+  }
+  if (!value.tools.every(validTool)) {
+    throw new Refusal("The app returned an invalid tool definition.", "invalid_agent_response");
+  }
+  return { ok: true, app: value.app, tools: value.tools };
+}
+function parseInvokeResponse(value) {
+  if (!isRecord(value) || value.ok !== true || !Object.prototype.hasOwnProperty.call(value, "result")) {
+    throw new Refusal("The app returned an unexpected tool response.", "invalid_agent_response");
+  }
+  return { ok: true, result: value.result };
+}
+function safeServerCode(value) {
+  return typeof value === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(value) ? value : void 0;
+}
+function redact(value, tokens) {
+  return tokens.reduce(
+    (text2, token) => token ? text2.split(token).join("[redacted]") : text2,
+    value
+  );
+}
+function redactValue(value, tokens) {
+  if (typeof value === "string") return redact(value, tokens);
+  if (Array.isArray(value)) return value.map((item) => redactValue(item, tokens));
+  if (isRecord(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [redact(key, tokens), redactValue(item, tokens)])
+    );
+  }
+  return value;
+}
+async function readResponseText(response) {
+  try {
+    return await readBoundedBodyText(response, MAX_RESPONSE_BYTES);
+  } catch (error) {
+    if (error instanceof BodyTooLargeError) {
+      throw new Refusal(
+        `App response exceeds the ${MAX_RESPONSE_BYTES}-byte limit.`,
+        "response_too_large"
+      );
+    }
+    throw error;
+  }
+}
+async function requestJson(url, init, token, timeout) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  try {
+    let response;
+    try {
+      response = await fetch(url, {
+        ...init,
+        headers: { ...init.headers, authorization: `Bearer ${token}` },
+        redirect: "manual",
+        signal: controller.signal
+      });
+    } catch (error) {
+      if (controller.signal.aborted || error instanceof Error && error.name === "AbortError") {
+        throw new Refusal(`Request timed out after ${timeout}ms.`, "agent_timeout");
+      }
+      throw new Refusal("Could not reach the app agent endpoint.", "agent_network_error");
+    }
+    if (response.status >= 300 && response.status < 400) {
+      await response.body?.cancel().catch(() => void 0);
+      throw new Refusal(
+        "App agent endpoint redirected; refusing to forward credentials.",
+        "agent_redirect_refused"
+      );
+    }
+    let text2;
+    try {
+      text2 = await readResponseText(response);
+    } catch (error) {
+      if (error instanceof Refusal) throw error;
+      if (controller.signal.aborted || error instanceof Error && error.name === "AbortError") {
+        throw new Refusal(`Request timed out after ${timeout}ms.`, "agent_timeout");
+      }
+      throw new Refusal("Could not read the app agent response.", "agent_network_error");
+    }
+    let body = null;
+    if (text2) {
+      try {
+        body = JSON.parse(text2);
+      } catch {
+        if (response.ok)
+          throw new Refusal("The app returned a non-JSON response.", "invalid_agent_response");
+      }
+    }
+    return { status: response.status, body, text: text2 };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function httpRefusal(response, tokens) {
+  const server = isRecord(response.body) ? response.body : void 0;
+  const code = safeServerCode(server?.code);
+  const message = typeof server?.error === "string" ? redact(server.error, tokens).slice(0, 500) : "";
+  if (response.status === 403) {
+    return new Refusal(
+      message || "You are not allowed to use this app agent.",
+      code ?? "agent_forbidden"
+    );
+  }
+  if (response.status === 404 && !server) {
+    return new Refusal(
+      "No agent endpoint answered for this app. Either the app name/id is wrong (`deepspace app list` shows yours), or the app does not register assistant tools \u2014 its worker needs `registerAgent(app, { tools, inApp: false })` deployed.",
+      "agent_endpoint_not_found"
+    );
+  }
+  return new Refusal(
+    message || `App agent request failed (${response.status}).`,
+    code ?? (response.status === 404 ? "agent_endpoint_not_found" : "agent_request_failed")
+  );
+}
+async function callAgent(target2, path, init, timeout) {
+  let token = await mintAgentToken(target2.url);
+  const tokens = [token];
+  let retried = false;
+  for (; ; ) {
+    const response = await requestJson(`${target2.url}${path}`, init, token, timeout);
+    if (response.status !== 401) {
+      if (response.status < 200 || response.status >= 300) throw httpRefusal(response, tokens);
+      return redactValue(response.body, tokens);
+    }
+    if (!retried) {
+      retried = true;
+      token = await mintAgentToken(target2.url);
+      tokens.push(token);
+      continue;
+    }
+    throw new Refusal(
+      "Authentication was rejected. Run `deepspace auth login` and try again.",
+      "not_authenticated",
+      { action: cliAction("deepspace", "auth", "login") }
+    );
+  }
+}
+async function runAgentTools(args) {
+  const target2 = resolveAgentTarget(args.app);
+  const body = parseToolsResponse(
+    await callAgent(target2, "/_deepspace/agent/tools", { method: "GET" }, DEFAULT_TIMEOUT_MS2)
+  );
+  if (!args.json) {
+    console.log(`App: ${body.app.name} (${body.app.id}, ${target2.url})`);
+    if (body.tools.length === 0) console.log("Tools: none");
+    else {
+      console.log("Tools:");
+      for (const tool of body.tools) {
+        console.log(`- ${tool.name}: ${tool.description}`);
+        console.log(`  Input: ${JSON.stringify(tool.inputSchema)}`);
+        if (tool.outputSchema !== void 0) {
+          console.log(`  Output: ${JSON.stringify(tool.outputSchema)}`);
+        }
+      }
+    }
+  }
+  return { data: { app: body.app, url: target2.url, tools: body.tools } };
+}
+async function runAgentInvoke(args) {
+  const target2 = resolveAgentTarget(args.app);
+  const input = await resolveAgentInput({ input: args.input, inputFile: args.inputFile });
+  const tool = args.tool;
+  if (typeof tool !== "string" || !tool)
+    throw new Refusal("Tool name is required.", "invalid_agent_tool");
+  const requestBody = serializeAgentInput(input);
+  const body = parseInvokeResponse(
+    await callAgent(
+      target2,
+      `/_deepspace/agent/tools/${encodeURIComponent(tool)}`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: requestBody
+      },
+      parseAgentTimeout(args.timeout)
+    )
+  );
+  if (!args.json) {
+    console.log(`App: ${args.app} (${target2.url})`);
+    console.log(`Tool: ${tool}`);
+    console.log("Result:");
+    console.log(JSON.stringify(body.result, null, 2));
+  }
+  return { data: { app: args.app, url: target2.url, tool, result: body.result } };
+}
+var tools = defineDeepspaceCommand({
+  meta: { name: "tools", description: "List the agent tools exposed by an app" },
+  args: {
+    app: { type: "positional", description: "Canonical app name or URL", required: true }
+  },
+  async run({ args }) {
+    return runAgentTools({ app: args.app, json: args.json });
+  }
+});
+var invoke2 = defineDeepspaceCommand({
+  meta: { name: "invoke", description: "Invoke an agent tool exposed by an app" },
+  args: {
+    app: { type: "positional", description: "Canonical app name or URL", required: true },
+    tool: { type: "positional", description: "Tool name", required: true },
+    input: { type: "string", description: "Inline JSON tool input" },
+    "input-file": { type: "string", description: "JSON input file (use - for stdin)" },
+    timeout: {
+      type: "string",
+      description: `Request timeout in milliseconds (default: ${DEFAULT_TIMEOUT_MS2})`
+    }
+  },
+  async run({ args }) {
+    return runAgentInvoke({
+      app: args.app,
+      tool: args.tool,
+      input: args.input,
+      inputFile: args["input-file"],
+      timeout: args.timeout,
+      json: args.json
+    });
+  }
+});
+var agent_default = defineCommand10({
+  meta: { name: "agent", description: "List and invoke an app\u2019s stateless local agent tools" },
+  subCommands: { tools, invoke: invoke2 }
+});
+
 // src/cli/commands/feedback.ts
 import * as p16 from "@clack/prompts";
 import { existsSync as existsSync25, readFileSync as readFileSync21 } from "fs";
@@ -11201,7 +11642,7 @@ Context: deepspace ${payload.cliVersion} \xB7 ${payload.nodeVersion} \xB7 ${payl
 });
 
 // src/cli/commands/secrets.ts
-import { defineCommand as defineCommand10 } from "citty";
+import { defineCommand as defineCommand11 } from "citty";
 import { readFileSync as readFileSync22 } from "fs";
 
 // src/cli/lib/citty-args.ts
@@ -11284,7 +11725,7 @@ function warnIfDebugRoutesEnabled(secrets) {
 var APPLY_HINT = "Run `deepspace deploy` to apply \u2014 secrets take effect at deploy time.";
 var APPLIES_AT_DEPLOY = { appliesAtDeploy: true, devRestartRequired: true };
 var LOCAL_DEV_HINT = "Running `deepspace dev start`? Restart it to load the change locally.";
-var list6 = defineCommand10({
+var list6 = defineCommand11({
   meta: { name: "list", description: "List masked secrets in a config" },
   args: {
     ...COMMON_ARGS,
@@ -11310,7 +11751,7 @@ var list6 = defineCommand10({
     }
   }
 });
-var set = defineCommand10({
+var set = defineCommand11({
   meta: { name: "set", description: "Set secrets from KEY=value pairs, or KEY --stdin" },
   args: {
     ...COMMON_ARGS,
@@ -11394,7 +11835,7 @@ var set = defineCommand10({
     );
   }
 });
-var get2 = defineCommand10({
+var get2 = defineCommand11({
   meta: { name: "get", description: "Get a secret; pass --plain to print the value" },
   args: {
     ...COMMON_ARGS,
@@ -11432,7 +11873,7 @@ var get2 = defineCommand10({
     );
   }
 });
-var del2 = defineCommand10({
+var del2 = defineCommand11({
   meta: { name: "delete", description: "Delete one or more secrets" },
   args: {
     ...COMMON_ARGS,
@@ -11468,7 +11909,7 @@ var del2 = defineCommand10({
     );
   }
 });
-var upload = defineCommand10({
+var upload = defineCommand11({
   meta: { name: "upload", description: "Upload secrets from a dotenv or JSON file" },
   args: {
     ...COMMON_ARGS,
@@ -11527,7 +11968,7 @@ async function readUploadSource(file) {
     );
   }
 }
-var download = defineCommand10({
+var download = defineCommand11({
   meta: { name: "download", description: "Download a config\u2019s secrets (dotenv/json/shell)" },
   args: {
     ...COMMON_ARGS,
@@ -11567,7 +12008,7 @@ var download = defineCommand10({
     process.stdout.write(formatSecretsDownload(secrets, format));
   }
 });
-var pull = defineCommand10({
+var pull = defineCommand11({
   meta: { name: "pull", description: "Refresh the .dev.vars cache from the app store" },
   args: { ...COMMON_ARGS },
   async run({ args }) {
@@ -11608,7 +12049,7 @@ var pull = defineCommand10({
     );
   }
 });
-var configsList = defineCommand10({
+var configsList = defineCommand11({
   meta: { name: "list", description: "List the app\u2019s configs" },
   args: { ...COMMON_ARGS },
   async run({ args }) {
@@ -11625,7 +12066,7 @@ var configsList = defineCommand10({
     });
   }
 });
-var configsCreate = defineCommand10({
+var configsCreate = defineCommand11({
   meta: { name: "create", description: "Create a config (optionally copying another)" },
   args: {
     ...COMMON_ARGS,
@@ -11659,7 +12100,7 @@ var configsCreate = defineCommand10({
     );
   }
 });
-var configsDelete = defineCommand10({
+var configsDelete = defineCommand11({
   meta: { name: "delete", description: "Delete a config and all of its secrets" },
   args: {
     ...COMMON_ARGS,
@@ -11704,11 +12145,11 @@ var configsDelete = defineCommand10({
     );
   }
 });
-var configs = defineCommand10({
+var configs = defineCommand11({
   meta: { name: "configs", description: "Manage the app\u2019s secrets configs" },
   subCommands: { list: configsList, create: configsCreate, delete: configsDelete }
 });
-var secrets_default = defineCommand10({
+var secrets_default = defineCommand11({
   meta: { name: "secrets", description: "Manage the app\u2019s secrets store" },
   subCommands: {
     list: list6,
@@ -11821,6 +12262,9 @@ var init_default = defineDeepspaceCommand({
         console.log(
           `Registered on ${DEEPSPACE_ENV} as a NEW app under ${accountLabel(token)}; the original is untouched.`
         );
+        console.log(
+          "Note: the fork keeps the wrangler `name` \u2014 its first deploy targets the SAME subdomain as the original. For a separate URL, change `name` in wrangler.toml (and APP_NAME) before deploying."
+        );
       } else {
         console.log(`Registered ${appId}${envSuffix} on ${DEEPSPACE_ENV} to ${accountLabel(token)}${commitNote}`);
         if (replacedMalformed !== null) {
@@ -11869,7 +12313,7 @@ var init_default = defineDeepspaceCommand({
 });
 
 // src/cli/commands/status.ts
-import { defineCommand as defineCommand11 } from "citty";
+import { defineCommand as defineCommand12 } from "citty";
 import * as p17 from "@clack/prompts";
 import { existsSync as existsSync26, readFileSync as readFileSync23 } from "fs";
 function timeAgo(iso) {
@@ -11913,7 +12357,7 @@ function resolveStatusApp(appDir, wranglerEnv) {
     return { appName, appId: null, appIdError: err.message };
   }
 }
-var status_default = defineCommand11({
+var status_default = defineCommand12({
   meta: {
     name: "status",
     description: "One screenful of current state \u2014 always names the platform plane (env, services) \u2014 plus session, app, workspace, and live release"
@@ -11972,6 +12416,7 @@ var status_default = defineCommand11({
       json.sessionError = sessionError("Not logged in. Run `deepspace auth login` first.");
     } else {
       let who = null;
+      let undecodableToken = false;
       try {
         const payload = decodeJwtPayload(
           readFileSync23(TOKEN_PATH, "utf-8").trim()
@@ -11979,13 +12424,39 @@ var status_default = defineCommand11({
         if (payload.email) who = payload.email;
         userId = payload.sub ?? null;
       } catch {
+        undecodableToken = existsSync26(TOKEN_PATH);
+      }
+      let sessionLineEmitted = false;
+      if (undecodableToken) {
+        try {
+          const healed = await ensureToken();
+          const payload = decodeJwtPayload(healed);
+          if (payload.email) who = payload.email;
+          userId = payload.sub ?? null;
+        } catch (err) {
+          sessionLineEmitted = true;
+          const offline = err instanceof TypeError || errorCode(err) === "network_error";
+          if (offline) {
+            lines.push(["Session", "logged in \xB7 stored token unreadable, could not verify offline"]);
+            json.loggedIn = true;
+          } else {
+            lines.push(["Session", "stored credentials unusable \u2014 run `deepspace auth login`"]);
+            facts.loggedIn = false;
+            json.loggedIn = false;
+            json.sessionError = sessionError(
+              "Stored credentials are unusable. Run `deepspace auth login`."
+            );
+          }
+        }
+      }
+      if (!sessionLineEmitted) {
+        lines.push([
+          "Session",
+          `${who ?? "logged in"} \xB7 renews on use (re-login only after 30 idle days)`
+        ]);
+        json.loggedIn = true;
+        if (who) json.user = who;
       }
-      lines.push([
-        "Session",
-        `${who ?? "logged in"} \xB7 renews on use (re-login only after 30 idle days)`
-      ]);
-      json.loggedIn = true;
-      if (who) json.user = who;
     }
     const appDir = findAppDir();
     if (!appDir) {
@@ -12120,9 +12591,10 @@ var status_default = defineCommand11({
             ]);
             json.source = { ...source, revision: sourceResult.value.revision };
           } else {
+            const observed = inferredGithub ? observedGitHubRepository(appDir) : null;
             lines.push([
               "Source",
-              `unclaimed \xB7 ${inferredGithub ? "first release claims GitHub (from this checkout\u2019s remote), permanently" : "first deploy or push claims DeepSpace, permanently"}`
+              `unclaimed \xB7 ${inferredGithub ? `first release claims GitHub${observed ? ` (${observed})` : ""} from this checkout\u2019s remote, permanently` : "first deploy or push claims DeepSpace, permanently"}`
             ]);
             json.source = null;
             json.sourceInference = inferredGithub ? "github" : "deepspace";
@@ -13156,7 +13628,7 @@ Re-run with --allow-do-deletion to accept the data loss.`,
 });
 
 // src/cli/commands/workspace.ts
-import { defineCommand as defineCommand12 } from "citty";
+import { defineCommand as defineCommand13 } from "citty";
 
 // src/cli/commands/workspace/new.ts
 import * as p25 from "@clack/prompts";
@@ -13744,9 +14216,9 @@ var newWorkspaceCommand = defineDeepspaceCommand({
   },
   async run({ args }) {
     const task = typeof args.task === "string" ? args.task.trim() : "";
-    if (!task) {
+    if (!task || task.startsWith("-")) {
       throw new Refusal(
-        'A workspace needs a task \u2014 pass -t "<what this workspace is for>" (it is shown to every collaborator and agent).',
+        'A workspace needs a task \u2014 pass -t "<what this workspace is for>" (quote it, and put flags like --json after it; it is shown to every collaborator and agent).',
         "invalid_task"
       );
     }
@@ -15048,7 +15520,7 @@ var dropWorkspaceCommand = defineDeepspaceCommand({
 });
 
 // src/cli/commands/workspace.ts
-var workspace_default = defineCommand12({
+var workspace_default = defineCommand13({
   meta: {
     name: "workspace",
     description: "Durable parallel-agent workspaces (new/attach/sync/list/status/land/drop)"
@@ -15097,7 +15569,7 @@ function formatEvent2(e, lands, actors) {
       detail = `"${String(s.task ?? "")}" from ${short(s.baseOid)}`;
       break;
     case "workspace.synced":
-      detail = `${e.subjectId ? `${e.subjectId} ` : ""}\u2192 ${short(s.headOid)}`;
+      detail = `${e.subjectId ? `${e.subjectId} ` : ""}${typeof s.task === "string" && s.task ? `"${s.task}" ` : ""}\u2192 ${short(s.headOid)}`;
       break;
     case "workspace.landed":
       detail = `"${String(s.task ?? "")}" \u2192 ${short(s.landedOid)} on ${String(s.into ?? "trunk")}`;
@@ -15227,7 +15699,7 @@ var activity_default = defineDeepspaceCommand({
 });
 
 // src/cli/commands/git-credential.ts
-import { defineCommand as defineCommand13 } from "citty";
+import { defineCommand as defineCommand14 } from "citty";
 function parseFields(input) {
   const fields = /* @__PURE__ */ new Map();
   for (const line of input.split("\n")) {
@@ -15269,7 +15741,7 @@ function declineHint(op, input, token, deployUrl) {
   }
   return "";
 }
-var git_credential_default = defineCommand13({
+var git_credential_default = defineCommand14({
   meta: {
     name: "git-credential",
     description: "Git credential helper (installed automatically; not for direct use)"
@@ -15368,6 +15840,7 @@ function reportSource(appId, state, json) {
     );
   }
   console.log(`Revision: ${state.revision}`);
+  console.log(`Registered: ${state.registered ? "yes" : "no"}`);
 }
 
 // src/cli/commands/update.ts
@@ -15378,7 +15851,7 @@ import { join as join28, resolve as resolve22 } from "path";
 // package.json
 var package_default = {
   name: "deepspace",
-  version: "0.28.0",
+  version: "0.28.2",
   engines: {
     node: ">=22.15.0 <23 || >=24 <25 || >=26 <27"
   },
@@ -15700,7 +16173,7 @@ var pkg = JSON.parse(readFileSync27(join29(__dirname, "..", "package.json"), "ut
 if (process.platform === "linux" && !process.env.SSL_CERT_FILE && existsSync31("/etc/ssl/certs/ca-certificates.crt")) {
   process.env.SSL_CERT_FILE = "/etc/ssl/certs/ca-certificates.crt";
 }
-var create2 = defineCommand14({
+var create2 = defineCommand15({
   meta: {
     name: "create",
     description: "Create a new DeepSpace app (runs create-deepspace; all flags are forwarded)"
@@ -15749,11 +16222,11 @@ var create2 = defineCommand14({
   }
 });
 var rename = (cmd, name) => ({ ...cmd, meta: { ...cmd.meta ?? {}, name } });
-var auth = defineCommand14({
+var auth = defineCommand15({
   meta: { name: "auth", description: "Session: login, logout, whoami" },
   subCommands: { login: login_default, logout: logout_default, whoami: whoami_default }
 });
-var app = defineCommand14({
+var app = defineCommand15({
   meta: {
     name: "app",
     description: "The app itself: create, init, list, files, source, update, undeploy, transfer, collaborators, domain, usage"
@@ -15772,11 +16245,11 @@ var app = defineCommand14({
     update: update_default
   }
 });
-var devGroup = defineCommand14({
+var devGroup = defineCommand15({
   meta: { name: "dev", description: "Local development" },
   subCommands: { start: rename(dev_default, "start"), kill: kill_default }
 });
-var testGroup = defineCommand14({
+var testGroup = defineCommand15({
   meta: { name: "test", description: "App tests and test tooling" },
   subCommands: {
     run: rename(test_default, "run"),
@@ -15784,7 +16257,7 @@ var testGroup = defineCommand14({
     accounts: rename(test_accounts_default, "accounts")
   }
 });
-var main = defineCommand14({
+var main = defineCommand15({
   meta: {
     name: "deepspace",
     version: pkg.version,
@@ -15810,6 +16283,7 @@ var main = defineCommand14({
     add: add_default,
     secrets: secrets_default,
     integrations: integrations_default,
+    agent: agent_default,
     auth,
     app,
     feedback: feedback_default,