@spacefast/common 0.0.24 → 0.2.1

package/dist/docs/agent-setup.d.ts

@@ -1,73 +1,104 @@
 import { type ConnectTarget, type ConnectTargetId } from "../agents/connect-targets.js";
+import type { AgentHandoffTarget } from "../contracts/device-auth.js";
 export declare const agentSetupUrl: string;
-export declare const agentSetupTextUrl: string;
 export declare const agentSetupHostLabel: string;
 export declare const agentSetupPrompt: string;
 export declare const anonymousPublishCurlCommand: string;
+export declare const AGENT_HANDOFF_TOKEN_PATTERN: RegExp;
 /**
- * Typed, safe decline states for the app-private redemption exchange.
- * `invalid_handoff` is the single answer for both an unknown document ID and a wrong secret, so a
- * decline never becomes an existence oracle; state-specific reasons are returned only after the
- * supplied secret authenticates the handoff. `already_redeemed` makes one-use explicit: after the
- * first exchange succeeds, the second fails with this reason. Declines are terminal and never
- * reveal whether a secret was close to correct.
+ * Decline states for the app-private redemption exchange. `invalid_handoff` is
+ * the single answer for both an unknown document ID and a wrong secret, so a
+ * decline never becomes an existence oracle; the other reasons are returned only
+ * after the supplied secret authenticates the handoff. Declines are terminal.
  */
 export declare const AGENT_HANDOFF_DECLINE_REASONS: readonly ["invalid_handoff", "expired", "already_redeemed", "revoked", "client_mismatch", "origin_mismatch"];
 export type AgentHandoffDeclineReason = (typeof AGENT_HANDOFF_DECLINE_REASONS)[number];
-export type AgentHandoffAction = Readonly<{
-    kind: "copy";
-    label: string;
-    sensitive: boolean;
-    value: string;
-}> | Readonly<{
-    kind: "open";
-    label: string;
-    href: string;
-}>;
 export type AgentHandoff = Readonly<{
-    actions: readonly AgentHandoffAction[];
-    documentUrl: string;
-    instructions: string;
     prompt: string;
+    secret: string;
+    url: string;
 }>;
 /**
  * The single shared grammar for handoff links:
- * `<access-origin>/agent/<documentId>/<oneUseToken>`. The document ID must match
- * `[A-Za-z0-9_-]{1,512}` and the token `[A-Za-z0-9_-]{16,512}`; the two must differ;
- * queries, fragments, and URL userinfo are forbidden. The URL must sit exactly on the caller's
- * configured HTTP(S) access origin; the clean static document may live on a separate explicitly
- * supplied dashboard origin.
- * Normalization is part of the contract: the input is WHATWG-URL-normalized first (backslashes,
- * dot segments, stray tab/CR/LF, empty userinfo, case, default ports), the grammar is enforced on
- * the normalized URL, and only the reconstructed canonical URL ever leaves this function.
- * Dashboard minting, CLI ingestion, and control-plane validation must all use this parser so the
- * grammar can never fork.
+ * `<access-origin>/handoffs/<token>`. The token is the bearer credential.
+ * Queries, fragments, and userinfo are forbidden. Dashboard minting, CLI
+ * ingestion, and control-plane redemption all use this parser so the grammar
+ * cannot fork.
  */
-export declare function parseAgentHandoffUrl(value: string, expectedOrigin: string, documentOrigin?: string): Readonly<{
-    documentId: string;
-    documentUrl: string;
+export type ParsedAgentHandoffUrl = Readonly<{
+    /** The canonical link, exactly as it must be presented back for redemption. */
     handoffUrl: string;
+    /** The bearer credential carried in the last path segment. */
     secret: string;
 }>;
+export declare function parseAgentHandoffUrl(value: string, expectedOrigin: string): ParsedAgentHandoffUrl;
 /** Connect targets whose handoff continues through the CLI stdin exchange. */
 export declare const AGENT_HANDOFF_CLI_TARGET_IDS: readonly ConnectTargetId[];
-export declare const AGENT_HANDOFF_PREAMBLE = "Talk to the user before installing tools or publishing. Confirm the file or folder they want to publish.";
-/** The fetch-safety contract: reading the document never consumes or leaks a handoff. */
-export declare const AGENT_HANDOFF_FETCH_SAFETY = "Keep the original handoff link private. Fetching this clean document URL did not use or send its credential; the credential is spent only by one successful exchange. An expired, used, or revoked link fails safely, so ask the user for a fresh one from the dashboard.";
-export declare const AGENT_HANDOFF_CREDENTIAL_HYGIENE = "Keep the private handoff URL out of commands, request URLs, logs, and replies.";
+export declare const AGENT_HANDOFF_PREAMBLE = "Talk to the user before you install tools or publish. Confirm the file or folder to publish.";
+export declare const AGENT_HANDOFF_CREDENTIAL_HYGIENE = "Keep the handoff URL out of command arguments, logs, and replies. It goes in exactly two places: the stdin prompt of `sf setup agent`, or the redeem request body.";
 export declare const AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE: string;
-export declare const AGENT_HANDOFF_BROWSER_APPROVAL_GUIDANCE = "When the client opens browser approval, ask the user to approve there before publishing.";
-export declare const AGENT_HANDOFF_PUBLISH_PROSE = "After approval, confirm the selected Space and permissions, then publish only the files the user approved. Report the bare Live and immutable Version addresses separately from the private Access URL; create a scoped Link when a recipient needs access.";
+export declare const AGENT_HANDOFF_PUBLISH_PROSE = "After login, confirm the Space and the files with the user, then publish the simplest way that fits: a one-off through `sf publish` or the publish API; a git checkout by pushing to the Space's push.new remote (`git.remoteUrl`); for repeat work the CLI is best, and `sf plugins` installs your client's plugin. Report the Live URL and the immutable Version URL; keep the private Access URL out of shared replies. Create a scoped Link only when a recipient needs access.";
 /** One target's Connect prose: blurb, copyable setup blocks, deeplink/download lines. */
 export declare function agentHandoffConnectSections(target: ConnectTarget): string[];
+/**
+ * Everything the agent needs to know about the link, said once, where it acts
+ * on it. "The URL you fetched" doubles as the only reference to the bearer —
+ * the document never repeats it, so the live secret stays out of whatever the
+ * agent caches or quotes next (`renderAgentHandoffDocument` takes an ORIGIN,
+ * never a URL, so the token cannot even reach the renderer).
+ */
+export declare const AGENT_HANDOFF_EXCHANGE_PROSE: string;
+/**
+ * The per-handoff setup document served from `/handoffs/<token>`.
+ *
+ * Takes the handoff's ORIGIN, never its URL: the bearer must not be able to
+ * reach this renderer, so it cannot end up in the bytes an agent caches.
+ *
+ * Reading order is the argument: what Spacefast is, talk to the user, exchange
+ * the link for a durable API key — the only expiring step, so it comes before
+ * client setup — then connect the client, then publish.
+ */
+export declare function renderAgentHandoffDocument(input: {
+    handoffOrigin: string;
+    mcpEndpoint: string;
+    targetId: AgentHandoffTarget;
+}): string;
+/**
+ * The document behind an anonymous (signed-out) handoff link. Same opening as
+ * the signed-in "any" document, ordered by usefulness: the two things the
+ * agent can actually do (publish with the no-account POST, or have the user
+ * sign in for a real handoff) come before the optional client catalog. The
+ * link itself grants nothing — its fetch only feeds the /start arrival watch —
+ * and the document doesn't narrate that; "Get a credential" states the one
+ * fact the agent needs.
+ */
+export declare function renderAnonymousAgentHandoffDocument(input: {
+    mcpEndpoint: string;
+}): string;
 /** Builds every copy-ready handoff artifact from one validated URL and target catalog row. */
 export declare function buildAgentHandoff(input: {
     expectedOrigin: string;
-    documentOrigin?: string;
     mcpEndpoint: string;
     targetId: ConnectTargetId;
     url: string;
 }): AgentHandoff;
+/**
+ * The signed-out half: a handoff that carries no team, no Space, and no
+ * authority, so its document is the public setup guide. It exists only so the
+ * fetch is observable — /start can tell the visitor their agent arrived without
+ * first making them sign up.
+ *
+ * The handoff line is APPENDED to the caller's prompt rather than replacing it:
+ * signed out, the prompt is still the thing carrying the user's actual task.
+ * One gesture, one sentence, single-sourced so no surface can word it
+ * differently. With no task selected the handoff line IS the prompt — the
+ * fetched document carries the whole setup, so the copy stays a single link.
+ */
+export declare function buildAnonymousAgentHandoff(input: {
+    expectedOrigin: string;
+    url: string;
+    /** The caller's own prompt text. The handoff line goes after it. */
+    context: string;
+}): AgentHandoff;
 export declare function renderAgentSetupTemplate(value: string): string;
-export declare function aiInstructionsText(): string;
 export declare function agentSetupMarkdown(): string;