Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,31 @@ that profile. Other hosts retain a mode-off notice and administrative diagnostic
without injecting recalled memory. Use `crosshead workspace remove` to detach a
project.

### Without a connection

Setup does not need the hosted service to be reachable. If `crosshead.sh`
cannot be reached (a sandbox with restricted egress, a CI job, a laptop
offline), the profile is still created and setup prints `registration:
deferred` with the network error (`--json` output carries
`registrationDeferred` and `registrationDeferredReason`). Capture and recall work locally at once, and
the profile tries to sign in on its next hosted request. That sign-in can still
be refused; `crosshead doctor` reports a profile that has never signed in and
why.

Setup still fails when the problem is the address rather than the network: a
response that refuses the sign-in, a redirect, a certificate error, a refused
connection to this machine (`localhost`, `127.0.0.1`), a proxy asking for
credentials or failing upstream, or (for any `--api-base` other than
`crosshead.sh`) a host name that does not exist. A proxy that refuses the
destination (HTTP 403) counts as unreachable; Node uses `HTTPS_PROXY` only when
`NODE_USE_ENV_PROXY=1` is set, and otherwise connects directly. A proxy that intercepts TLS and
answers with its own page or certificate is not recognised and fails setup;
use the local-only profile below in that case.

For a profile that never contacts a hosted service, pass
`--api-base http://127.0.0.1:0`. Hot memory, hooks and handoff capsules work;
hosted recall, sync between machines and billing do not.

Local-only checkpoints are stored per profile. A legacy flat store remains
readable for its sole existing local-only profile, whose identity is pinned
before creating another profile. If several profiles already shared an unowned
Expand Down
1 change: 1 addition & 0 deletions src/runtime/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -300,6 +300,7 @@ export const runOnlyBotsCtlCli = async (
capabilityHelpLine,
"crosshead keygen [--json]",
"crosshead keygen --setup --profile <name> --api-base <url> [--home <path>] [--memory-mode assist] [--workspace-scope repo|workspace|global] [--json]",
" (--api-base http://127.0.0.1:0 creates a local-only profile; an unreachable service defers sign-in instead of failing setup)",
"crosshead setup --profile <name> --api-base <url> --npub <npub> --nsec <nsec> [--memory-mode assist]",
"crosshead start [--home <path>] [--port <port>]",
"crosshead stop [--home <path>]",
Expand Down
15 changes: 14 additions & 1 deletion src/runtime/cli/core.ts
Original file line number Diff line number Diff line change
Expand Up @@ -131,9 +131,20 @@ export const setupProfileFromCli = async (argv: string[]): Promise<string> => {
npub: String(flags.npub ?? ""),
nsec: String(flags.nsec ?? ""),
});
return `Configured runtime profile ${profile.name} for ${profile.npub}`;
if (flags.json) {
return JSON.stringify({
profile: profile.name, npub: profile.npub, apiBase: profile.apiBase, memoryMode: profile.memoryMode,
...(profile.registrationDeferred ? { registrationDeferred: true, registrationDeferredReason: profile.registrationDeferredReason ?? null } : {}),
}, null, 2);
}
return [`Configured runtime profile ${profile.name} for ${profile.npub}`, ...registrationDeferredLines(profile)].join("\n");
};

export const registrationDeferredLines = (profile: { apiBase: string; registrationDeferred?: boolean; registrationDeferredReason?: string }): string[] =>
profile.registrationDeferred
? [`registration: deferred; ${profile.apiBase} could not be reached${profile.registrationDeferredReason ? ` (${profile.registrationDeferredReason})` : ""}. Local capture and recall work now, and the profile signs in on its first successful request; crosshead doctor shows whether it has.`]
: [];

export const keygenFromCli = async (argv: string[]): Promise<string> => {
const { flags } = parseArgs(argv);
const identity = generateRuntimeIdentity();
Expand Down Expand Up @@ -161,6 +172,7 @@ export const keygenFromCli = async (argv: string[]): Promise<string> => {
memoryMode: profile.memoryMode,
workspaceScope: profile.workspaceScope,
secureStoreMode: profile.secureStoreMode,
...(profile.registrationDeferred ? { registrationDeferred: true, registrationDeferredReason: profile.registrationDeferredReason ?? null } : {}),
};
return flags.json
? JSON.stringify(result, null, 2)
Expand All @@ -171,6 +183,7 @@ export const keygenFromCli = async (argv: string[]): Promise<string> => {
`memory_mode: ${profile.memoryMode}`,
`workspace_scope: ${profile.workspaceScope}`,
`secure_store: ${profile.secureStoreMode}`,
...registrationDeferredLines(profile),
].join("\n");
};

Expand Down
11 changes: 9 additions & 2 deletions src/runtime/cli/quickstart.ts
Original file line number Diff line number Diff line change
Expand Up @@ -205,16 +205,22 @@ export const quickstartFromCli = async (argv: string[], paths: QuickstartCliPath

const config = loadRuntimeConfig(runtimePaths);
const existingProfile = loadProfile(runtimePaths, profileName);
let registration: { registrationDeferred: true; registrationDeferredReason: string | null } | null = null;
if (!existingProfile) {
if (!apiBase) {
throw new Error("quickstart requires --api-base <url> when the selected profile does not exist");
}
const profileOutput = await keygenFromCli([...profileArgs, "--setup", "--json"]);
const parsed = JSON.parse(profileOutput) as { npub?: string; apiBase?: string };
const parsed = JSON.parse(profileOutput) as { npub?: string; apiBase?: string; registrationDeferred?: boolean; registrationDeferredReason?: string | null };
if (parsed.registrationDeferred) registration = { registrationDeferred: true, registrationDeferredReason: parsed.registrationDeferredReason ?? null };
steps.push({
id: "profile",
ok: true,
detail: `configured ${profileName} for ${parsed.apiBase ?? apiBase} with generated runtime identity ${parsed.npub ?? "unknown"}`,
detail: `configured ${profileName} for ${parsed.apiBase ?? apiBase} with generated runtime identity ${parsed.npub ?? "unknown"}${
parsed.registrationDeferred
? `; registration: deferred, the service could not be reached${parsed.registrationDeferredReason ? ` (${parsed.registrationDeferredReason})` : ""}; local capture and recall work now and sign-in happens on the next hosted request`
: ""
}`,
});
} else {
steps.push({
Expand Down Expand Up @@ -305,6 +311,7 @@ export const quickstartFromCli = async (argv: string[], paths: QuickstartCliPath
firstValueCommand: `crosshead memory hot --home ${runtimePaths.home} --profile ${profileName}`,
billingCommand: `crosshead billing status --home ${runtimePaths.home} --profile ${profileName}`,
paymentBoundary: "Agents may create/show checkout links or invoices, but a human must submit payment.",
...(registration ?? {}),
};
return flags.json ? JSON.stringify(result, null, 2) : formatQuickstart(result);
};
Expand Down
14 changes: 10 additions & 4 deletions src/runtime/cli/workspace.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import {
import { isRuntimeProfileName } from "../runtime-env";
import { uninstallCodexFromCli } from "../codex-adapter";
import { uninstallClaudeCodeFromCli } from "../claude-code-adapter";
import { installCoreFromCli, keygenFromCli } from "./core";
import { installCoreFromCli, keygenFromCli, registrationDeferredLines } from "./core";
import { ensureQuickstartDaemon, type QuickstartCliPaths } from "./quickstart";

type Flags = Record<string, string | boolean>;
Expand Down Expand Up @@ -228,6 +228,7 @@ export const scopedQuickstartFromCli = async (flags: Flags, scripts: QuickstartC
return flags.json ? JSON.stringify({ applied: false, ...preview }, null, 2) : runtimePlan + profilePlan + describePlan(preview);
}
if (flow && !await flow.confirm(runtimePlan + profilePlan + describePlan(preview))) return "Setup cancelled.";
const deferred: Array<{ profile: string; apiBase: string; reason: string | null }> = [];
const daemon = await withWorkspaceSetupLock(paths, async () => {
assertWorkspacePlanCurrent(plan);
if (names.some((name) => profileSnapshot(paths, name) !== profilesBefore.get(name))) {
Expand All @@ -240,8 +241,9 @@ export const scopedQuickstartFromCli = async (flags: Flags, scripts: QuickstartC
await installCoreFromCli([...args, "--channel", channel], scripts.cliScriptPath, scripts.daemonScriptPath);
}
for (const name of newProfiles) {
await keygenFromCli([...args, "--setup", "--profile", name, "--api-base", apiBase!, "--memory-mode", mode,
"--workspace-scope", "repo", "--no-default", "--create-only", "--json"]);
const created = JSON.parse(await keygenFromCli([...args, "--setup", "--profile", name, "--api-base", apiBase!, "--memory-mode", mode,
"--workspace-scope", "repo", "--no-default", "--create-only", "--json"])) as { registrationDeferred?: boolean; registrationDeferredReason?: string | null };
if (created.registrationDeferred) deferred.push({ profile: name, apiBase: apiBase!, reason: created.registrationDeferredReason ?? null });
}
applyWorkspaceHookPlan(plan);
const result = enabled(flags, "no-start") ? null : await ensureQuickstartDaemon({
Expand All @@ -252,9 +254,13 @@ export const scopedQuickstartFromCli = async (flags: Flags, scripts: QuickstartC
const inspection = inspectWorkspaceHooks(options.home);
const checks = scope === "project" ? [...new Set(targets.map((target) => workspaceProjectRoot(target.directory)))] : [process.cwd()];
return flags.json
? JSON.stringify({ command: "quickstart", applied: true, home: paths.home, profiles: names, daemon, ...inspection }, null, 2)
? JSON.stringify({ command: "quickstart", applied: true, home: paths.home, profiles: names, daemon, ...inspection,
// Same fields as keygen and quickstart; one entry per profile created here.
...(deferred.length > 0 ? { registrationDeferred: true, registrationDeferredReason: deferred[0]!.reason, registrationDeferredProfiles: deferred } : {}) }, null, 2)
: [
"Crosshead setup complete.",
...deferred.flatMap((entry) => registrationDeferredLines({ apiBase: entry.apiBase, registrationDeferred: true, registrationDeferredReason: entry.reason ?? undefined })
.map((line) => `${entry.profile} ${line}`)),
...(daemon ? [daemon.detail] : []),
formatWorkspaceHookInspection(inspection),
...checks.map((root) => `Verify from a fresh session with crosshead workspace check --workspace-root ${shellQuote(root)}${options.home ? ` --home ${shellQuote(paths.home)}` : ""}`),
Expand Down
48 changes: 48 additions & 0 deletions src/runtime/hosted-client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -246,6 +246,54 @@ export class HostedOnlyBotsRequestError extends Error {
}
}

export type FetchCause = { code: string | null; message: string };
export const fetchCauses = (error: unknown, depth = 0): FetchCause[] => {
if (!error || typeof error !== "object" || depth > 4) return [];
const record = error as { code?: unknown; message?: unknown; cause?: unknown; errors?: unknown };
return [
{ code: typeof record.code === "string" ? record.code : null, message: typeof record.message === "string" ? record.message : "" },
...fetchCauses(record.cause, depth + 1),
...(Array.isArray(record.errors) ? record.errors.flatMap((entry) => fetchCauses(entry, depth + 1)) : []),
];
};
// An egress proxy that refuses the tunnel (a sandbox allowlist, a corporate proxy) is the network
// saying "not from here", the same as a refused connection.
export const PROXY_REFUSAL = /Proxy response \((\d{3})\) !== 200 when HTTP Tunneling/;

const FETCH_CODE_LABELS: Record<string, string> = {
ENOTFOUND: "host name not found",
EAI_AGAIN: "DNS lookup unavailable",
EAI_FAIL: "DNS lookup failed",
ECONNREFUSED: "connection refused",
ECONNRESET: "connection reset",
ETIMEDOUT: "connection timed out",
UND_ERR_CONNECT_TIMEOUT: "connection timed out",
ENETUNREACH: "network unreachable",
EHOSTUNREACH: "host unreachable",
EPERM: "connection not permitted",
EACCES: "connection not permitted",
UND_ERR_SOCKET: "connection closed by the other side",
};
// Fixed strings that undici itself produces; anything else may carry text from the other end.
const FIXED_FETCH_MESSAGES = new Set(["unexpected redirect", "bad port"]);
const SAFE_FETCH_CODE = /^[A-Z][A-Z0-9_]{1,63}$/;

/**
* A one-line, locally safe description of why a fetch failed. Only error codes, undici's own
* fixed messages and a proxy's status are used: free-text cause messages can carry text chosen by
* the remote end (for example the names in a mismatched TLS certificate).
*/
export const describeFetchFailure = (error: unknown): string => {
if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) return "timed out";
const causes = error instanceof Error ? fetchCauses(error.cause) : [];
const proxy = causes.map((cause) => PROXY_REFUSAL.exec(cause.message)).find(Boolean);
if (proxy) return `proxy answered HTTP ${proxy[1]}`;
const code = causes.map((cause) => cause.code).filter((value): value is string => Boolean(value && SAFE_FETCH_CODE.test(value))).at(-1);
if (code) return FETCH_CODE_LABELS[code] ? `${FETCH_CODE_LABELS[code]} (${code})` : code;
const fixed = causes.map((cause) => cause.message.trim()).find((message) => FIXED_FETCH_MESSAGES.has(message));
return fixed ?? "network request failed";
};

/**
* Classify a failed hosted request for local diagnostics without copying its
* message, URL, headers or body: a timeout, an HTTP status/code, or an error name.
Expand Down
77 changes: 73 additions & 4 deletions src/runtime/local-runtime.ts
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,8 @@ import * as tar from "tar";
import { OperatorRuntimePolicyBroker, type OperatorWorkspaceManifest } from "./operator-policy";
import { HOSTED_PI_CONTROLLER_ADAPTER, HOSTED_PI_CONTROLLER_MANIFEST, hostedControllerProcessIsLive, type HostedControllerProcess } from "./hosted-pi-controller-manifest";
import { acquireRuntimeDaemonOwnership, daemonOwnerIsLive, probeRuntimeDaemonHealth, readDaemonOwnershipState, type RuntimeDaemonOwnership } from "./daemon-ownership";
import { HostedOnlyBotsClient, type HostedSession } from "./hosted-client";
import { describeFetchFailure, fetchCauses, HostedOnlyBotsClient, HostedOnlyBotsRequestError, PROXY_REFUSAL, type HostedSession } from "./hosted-client";
export { describeFetchFailure } from "./hosted-client";
import { isLocalOnlyRuntimeProfile, preserveLegacyLocalHotOwner, readLocalHotMemory } from "./local-hot-memory";
import { searchHotCheckpoints } from "./hot-continuity";
import {
Expand Down Expand Up @@ -1285,7 +1286,49 @@ export const uninstallRuntimeCore = async (home?: string): Promise<void> => {
}
};

export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): Promise<RuntimeProfile> => {
// Node's fetch reports nearly every transport failure as TypeError("fetch failed") and puts the
// real reason in `cause` (sometimes an AggregateError, one entry per address tried). Only these
// codes mean "no route to the service right now". A redirect, a certificate problem or a proxy
// error means something answered, or the address is wrong, and setup must say so instead.
const NETWORK_UNREACHABLE_CODES = new Set([
"ECONNREFUSED", "ENETUNREACH", "EHOSTUNREACH", "ENETDOWN", "EHOSTDOWN", "ETIMEDOUT", "ECONNRESET",
"EAI_AGAIN", "EAI_FAIL", "EADDRNOTAVAIL", "EPIPE", "UND_ERR_CONNECT_TIMEOUT",
// Sandboxes (macOS seatbelt, Linux seccomp) deny connect() itself with these.
"EPERM", "EACCES",
]);
const DEFAULT_HOSTED_HOSTS = new Set(["crosshead.sh", "www.crosshead.sh"]);

/**
* Why the hosted service could not be reached at all, or null when the failure is something
* setup must report: an HTTP answer, a failed challenge, a redirect, a certificate error, or a
* host name that does not exist. A proxy that refuses the tunnel counts as unreachable. A name that does not resolve is treated as offline
* only for the default service, where it means DNS is unavailable rather than a typo.
*/
export const hostedServiceUnreachableReason = (error: unknown, apiBase: string): string | null => {
if (!(error instanceof Error) || error instanceof HostedOnlyBotsRequestError) return null;
let host = "";
try { host = new URL(apiBase).hostname; } catch { /* an invalid URL fails elsewhere */ }
// This machine cannot be "offline" from itself: any failure to reach a loopback address,
// including a timeout, is a wrong port or a stopped or hung local server, which setup must report.
if (/^(localhost\.?|.+\.localhost\.?|127(\.\d{1,3}){3}|0\.0\.0\.0|\[::1?\]|\[::ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}\])$/i.test(host)) return null;
if (error.name === "TimeoutError" || error.name === "AbortError") return "timed out";
if (error.name !== "TypeError" || !/fetch failed/i.test(error.message)) return null;
const causes = fetchCauses(error.cause);
const codes = causes.flatMap((cause) => (cause.code ? [cause.code] : []));
const unreachable = codes.find((code) => NETWORK_UNREACHABLE_CODES.has(code));
if (unreachable) return unreachable;
// Only a proxy that forbids the destination means "not from here". 407 is missing proxy
// credentials and 502/504 usually a host the proxy could not resolve: both need fixing, not waiting.
const proxy = causes.map((cause) => PROXY_REFUSAL.exec(cause.message)).find(Boolean);
if (proxy?.[1] === "403") return "proxy refused the connection (HTTP 403)";
if (codes.includes("ENOTFOUND")) return DEFAULT_HOSTED_HOSTS.has(host) ? "ENOTFOUND" : null;
return null;
};

/** The saved profile, plus whether sign-in with the hosted service was put off because it was unreachable. */
export type SetupRuntimeProfileResult = RuntimeProfile & { registrationDeferred?: true; registrationDeferredReason?: string };

export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions): Promise<SetupRuntimeProfileResult> => {
try {
const decodedNpub = nip19.decode(options.npub);
const decodedNsec = nip19.decode(options.nsec);
Expand All @@ -1306,14 +1349,39 @@ export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions):
if (options.createOnly && loadProfile(paths, options.profileName)) throw new Error(`Profile ${options.profileName} already exists`);
const secret = loadSecret(paths, options.profileName);
const localOnlyProfile = isLocalOnlyRuntimeProfile({ apiBase: options.apiBase });
// Capture and recall are local-first, so a machine with no route to the service (a sandbox, a
// CI job, a laptop offline) can still be set up. The client signs in on its first hosted request.
let registrationDeferred = false;
let registrationDeferredReason: string | undefined;
const session = localOnlyProfile
? null
: await new HostedOnlyBotsClient({
apiBase: options.apiBase,
npub: options.npub,
nsec: options.nsec,
session: secret?.session ?? null,
}).ensureSession();
}).ensureSession().catch((error: unknown) => {
const reason = hostedServiceUnreachableReason(error, options.apiBase);
if (reason === null) {
// Name the real cause: a bare "fetch failed" hides a typo in --api-base or a certificate problem.
if (error instanceof TypeError && /fetch failed/i.test(error.message)) {
const reason = describeFetchFailure(error);
throw new Error(`Could not sign in to ${options.apiBase}: ${reason}. Check --api-base${
reason.startsWith("proxy") ? " and the proxy settings (HTTPS_PROXY, NODE_USE_ENV_PROXY)" : ""}.`, { cause: error });
}
if (error instanceof HostedOnlyBotsRequestError && error.status === 404) {
// Keep the type, status and code: --json error output reports them.
throw new HostedOnlyBotsRequestError({
message: `Could not sign in to ${options.apiBase}: it answered 404, so it is probably not a Crosshead service. Check --api-base.`,
status: error.status, code: error.code, details: error.details, retryAfterMs: error.retryAfterMs,
});
}
throw error;
}
registrationDeferred = true;
registrationDeferredReason = reason;
return null;
});

const profile: RuntimeProfile = {
name: options.profileName,
Expand Down Expand Up @@ -1353,8 +1421,9 @@ export const setupRuntimeProfile = async (options: SetupRuntimeProfileOptions):
npub: profile.npub,
apiBase: profile.apiBase,
memoryMode: profile.memoryMode,
...(registrationDeferred ? { registrationDeferred: true, registrationDeferredReason } : {}),
});
return profile;
return registrationDeferred ? { ...profile, registrationDeferred: true, registrationDeferredReason } : profile;
};

const installManagedAdapter = async (
Expand Down
Loading
Loading