@codeworksh/cli 0.0.1-dev.20260923102823 → 0.0.1-dev.20260925163815

package/error-CxoEKg-4.mjs

@@ -0,0 +1,610 @@
+import { Deferred, Duration, Effect, Layer, Predicate, Schema, Stream } from "effect";
+import { Model } from "@codeworksh/aikit";
+import { Control, Event, EventList, EventSchema, Location, ModelCatalog, Plugin, PromptSchema, Runner, Sandbox, SandboxError, Session, SessionStore, Settings, optional } from "@codeworksh/harness/effect";
+import { SandboxProvider } from "@codeworksh/harness/sandbox";
+import { NodeSocket } from "@effect/platform-node";
+import { Rpc, RpcClient, RpcGroup, RpcSerialization } from "effect/unstable/rpc";
+//#region src/server/envelope.ts
+/**
+* The wire form of an `EventSchema.Payload`. `data` is carried in its encoded
+* form — decoded payloads are not wire-safe (`Schema.Duration`, aikit class
+* transforms) — so clients decode it lazily through their own copy of the
+* registry and can skip types they do not know.
+*/
+const EventEnvelope = Schema.Struct({
+	id: EventSchema.ID,
+	type: Schema.String,
+	durable: optional(Schema.Struct({
+		aggregateId: Schema.String,
+		seq: Schema.Int,
+		version: Schema.Int
+	})),
+	metadata: optional(Schema.Record(Schema.String, Schema.String)),
+	data: Schema.Unknown
+});
+var UnknownEventTypeError = class extends Schema.TaggedError()("UnknownEventTypeError", { type: Schema.String }) {};
+/** The transport's own readiness frame; it has no meaning inside the harness. */
+const Connected = EventSchema.define({
+	type: "server.connected",
+	schema: {}
+});
+/**
+* What a stock client can decode: the harness's public events plus the frames
+* the transport adds itself. A server may know more than this -- plugins
+* register their own types -- which is exactly why `data` crosses the wire
+* encoded and is decoded lazily, so an unknown type is skipped, not fatal.
+*/
+const core = EventSchema.latest([...EventList.PublicDefinitions, Connected]);
+const Core = (type) => core.get(type);
+var EncodingError = class extends Schema.TaggedError()("EventEncodingError", {
+	type: Schema.String,
+	cause: Schema.Defect()
+}) {};
+const encode = Effect.fn("Envelope.encode")(function* (payload, registry = Core) {
+	const definition = registry(payload.type);
+	if (definition === void 0) return yield* new UnknownEventTypeError({ type: payload.type });
+	const data = yield* Schema.encodeEffect(definition.data)(payload.data).pipe(Effect.mapError((cause) => new EncodingError({
+		type: payload.type,
+		cause
+	})));
+	return {
+		id: payload.id,
+		type: payload.type,
+		...payload.durable === void 0 ? {} : { durable: payload.durable },
+		...payload.metadata === void 0 ? {} : { metadata: payload.metadata },
+		data
+	};
+});
+const decode = Effect.fn("Envelope.decode")(function* (envelope, registry = Core) {
+	const definition = registry(envelope.type);
+	if (definition === void 0) return yield* new UnknownEventTypeError({ type: envelope.type });
+	const data = yield* Schema.decodeEffect(definition.data)(envelope.data);
+	return {
+		id: envelope.id,
+		type: envelope.type,
+		...envelope.durable === void 0 ? {} : { durable: envelope.durable },
+		...envelope.metadata === void 0 ? {} : { metadata: envelope.metadata },
+		data
+	};
+});
+//#endregion
+//#region src/server/contract.ts
+const SandboxInfo = Schema.Struct({
+	id: Sandbox.SandboxInstance.ID,
+	driver: Schema.String,
+	kind: Sandbox.SandboxInstance.Kind,
+	providerResourceId: Schema.OptionFromNullOr(Schema.String),
+	ownership: Sandbox.SandboxInstance.Ownership,
+	status: Sandbox.SandboxInstance.Status,
+	usage: Sandbox.SandboxInstance.Usage,
+	refCount: Schema.Int,
+	createdAt: Schema.DateFromString,
+	updatedAt: Schema.DateFromString
+});
+const SessionInfo = Schema.Struct({
+	id: Session.SessionSchema.ID,
+	title: Schema.String,
+	directory: Session.AbsolutePath,
+	/** The host directory this session is anchored to. Absent when it has none. */
+	hostDir: optional(Session.AbsolutePath),
+	sandbox: optional(SandboxInfo)
+});
+const RuntimeConfig = Schema.Struct({
+	model: optional(Schema.Struct({
+		provider: Schema.String,
+		id: Schema.String
+	})),
+	thinkingLevel: optional(Schema.Enum(Model.ThinkingLevelEnum))
+});
+const SandboxRef = Sandbox.Selection;
+var OAuthError$1 = class extends Schema.TaggedError()("Server.OAuthError", { message: Schema.String }) {};
+/** OAuth providers whose credentials this server stores. */
+const OAuthProvider = Schema.Literals(["openai-codex", "github-copilot"]);
+/**
+* Credentials as the provider's aikit module persists them. The union is
+* discriminated by `provider` so one set of RPCs serves every login.
+*/
+const OAuthCredentials = Schema.Union([Schema.Struct({
+	provider: Schema.Literal("openai-codex"),
+	access: Schema.String,
+	refresh: Schema.String,
+	expires: Schema.Finite,
+	accountId: Schema.String
+}), Schema.Struct({
+	provider: Schema.Literal("github-copilot"),
+	access: Schema.String,
+	refresh: Schema.String,
+	expires: Schema.Finite,
+	enterpriseUrl: optional(Schema.String),
+	apiEndpoint: optional(Schema.String),
+	availableModelIds: optional(Schema.Array(Schema.String))
+})]);
+/** What a login looks like from the outside: never the tokens themselves. */
+const OAuthInfo = Schema.Struct({
+	provider: OAuthProvider,
+	/** Epoch millis, or 0 for a credential that does not expire. */
+	expires: Schema.Finite,
+	accountId: optional(Schema.String),
+	apiEndpoint: optional(Schema.String),
+	enterpriseUrl: optional(Schema.String),
+	availableModels: optional(Schema.Int)
+});
+const SessionErrors = Schema.Union([
+	SessionStore.SessionNotFoundError,
+	SessionStore.SessionLinkedSpaceNotFoundError,
+	SessionStore.RelinkError
+]);
+const SandboxErrors = Schema.Union([
+	SandboxError.SandboxNotFoundError,
+	SandboxError.SandboxDriverNotRegisteredError,
+	SandboxError.SandboxDriverRegistrationError,
+	SandboxError.SandboxUnsupportedError,
+	SandboxError.SandboxProviderError,
+	SandboxError.SandboxUnavailError,
+	SandboxError.SandboxRemovedError,
+	SandboxError.SandboxTransitionConflictError,
+	SandboxError.SandboxBusyError
+]);
+const LocationErrors = Schema.Union([Location.DirectoryNotFoundError, Location.NotDirectoryError]);
+const Api = RpcGroup.make(
+	Rpc.make("auth.save", {
+		payload: { credentials: OAuthCredentials },
+		success: OAuthInfo,
+		error: OAuthError$1
+	}),
+	Rpc.make("auth.status", {
+		payload: { provider: OAuthProvider },
+		success: Schema.NullOr(OAuthInfo),
+		error: OAuthError$1
+	}),
+	Rpc.make("auth.refresh", {
+		payload: { provider: OAuthProvider },
+		success: Schema.NullOr(OAuthInfo),
+		error: OAuthError$1
+	}),
+	Rpc.make("auth.logout", {
+		payload: { provider: OAuthProvider },
+		success: Schema.Void,
+		error: OAuthError$1
+	}),
+	Rpc.make("session.create", {
+		payload: {
+			title: optional(Schema.String),
+			directory: optional(Schema.String),
+			/**
+			* The host directory this session is anchored to, usually the caller's project root.
+			* Unrelated to `directory`, which names a place inside the session's space.
+			*
+			* It is an anchor and nothing more: whatever needs a host-side directory resolves from
+			* here rather than from wherever the server happens to be running. What reads it is the
+			* reader's business, not this field's.
+			*
+			* Optional and honoured as given. Omitting it is normal, not a failure.
+			*/
+			hostDir: optional(Session.AbsolutePath),
+			sandbox: optional(SandboxRef),
+			runtime: optional(RuntimeConfig)
+		},
+		success: SessionInfo,
+		error: Schema.Union([
+			SessionErrors,
+			SandboxErrors,
+			LocationErrors
+		])
+	}),
+	Rpc.make("session.list", {
+		payload: {},
+		success: Schema.Array(SessionInfo)
+	}),
+	Rpc.make("session.configure", {
+		payload: {
+			sessionId: Session.SessionSchema.ID,
+			runtime: RuntimeConfig
+		},
+		success: SessionInfo,
+		error: SessionStore.SessionNotFoundError
+	}),
+	Rpc.make("session.info", {
+		payload: { sessionId: Session.SessionSchema.ID },
+		success: SessionInfo,
+		error: SessionStore.SessionNotFoundError
+	}),
+	/**
+	* Point an existing session at a host directory, or clear it with `null`.
+	*
+	* Not `session.relink`: that moves where the *work* happens, this changes which host directory
+	* the session is *anchored to*. Conflating them would recreate exactly the `cwd`/`hostDir`
+	* confusion the split exists to remove, which is why they sound alike and stay apart.
+	*/
+	Rpc.make("session.link", {
+		payload: {
+			sessionId: Session.SessionSchema.ID,
+			/** Absent clears the anchor, leaving the session with no host directory. */
+			hostDir: optional(Session.AbsolutePath)
+		},
+		success: SessionInfo,
+		error: SessionStore.SessionNotFoundError
+	}),
+	Rpc.make("session.relink", {
+		payload: {
+			sessionId: Session.SessionSchema.ID,
+			sandbox: optional(SandboxRef),
+			directory: optional(Schema.String)
+		},
+		success: SessionInfo,
+		error: Schema.Union([
+			SessionErrors,
+			SandboxErrors,
+			LocationErrors
+		])
+	}),
+	Rpc.make("session.prompt", {
+		payload: {
+			sessionId: Session.SessionSchema.ID,
+			text: Schema.String,
+			delivery: optional(PromptSchema.Delivery),
+			id: optional(Session.SessionMessageSchema.ID)
+		},
+		success: Schema.Void,
+		error: Schema.Union([SessionStore.SessionNotFoundError, Control.PromptConflictError])
+	}),
+	Rpc.make("session.interrupt", {
+		payload: { sessionId: Session.SessionSchema.ID },
+		success: Schema.Struct({ interrupted: Schema.Boolean })
+	}),
+	/**
+	* Whether a prompt materialized into the conversation. An admitted prompt
+	* that is still queued has no entry yet, so this is the projection a client
+	* reconciles against when the volatile stream left it unsure
+	*/
+	Rpc.make("session.message", {
+		payload: {
+			sessionId: Session.SessionSchema.ID,
+			messageId: Session.SessionMessageSchema.ID
+		},
+		success: Schema.Struct({ found: Schema.Boolean })
+	}),
+	Rpc.make("session.wait", {
+		payload: { sessionId: Session.SessionSchema.ID },
+		success: Schema.Void,
+		error: SessionStore.SessionNotFoundError
+	}),
+	/**
+	* Re-import every configured plugin, for the whole server.
+	*
+	* The one thing an exchange cannot notice on its own: a local plugin whose contents changed
+	* while its path did not. A failure keeps the previous set and is reported here rather than
+	* emptying a running server's tool registry.
+	*/
+	Rpc.make("plugin.reload", {
+		payload: {},
+		success: Schema.Struct({
+			plugins: Schema.Int,
+			failure: optional(Schema.String)
+		})
+	}),
+	Rpc.make("sandbox.drivers", {
+		payload: {},
+		success: Schema.Array(Schema.Struct({
+			name: Schema.String,
+			kind: Schema.String
+		}))
+	}),
+	Rpc.make("sandbox.list", {
+		payload: {},
+		success: Schema.Array(SandboxInfo)
+	}),
+	Rpc.make("sandbox.create", {
+		payload: { driver: Schema.String },
+		success: SandboxInfo,
+		error: SandboxErrors
+	}),
+	Rpc.make("sandbox.register", {
+		payload: {
+			driver: Schema.String,
+			providerResourceId: Schema.String
+		},
+		success: SandboxInfo,
+		error: SandboxErrors
+	}),
+	Rpc.make("sandbox.stop", {
+		payload: { sandboxId: Sandbox.SandboxInstance.ID },
+		success: Schema.Void,
+		error: SandboxErrors
+	}),
+	Rpc.make("event.subscribe", {
+		payload: {},
+		success: EventEnvelope,
+		error: Schema.Union([Event.SubscriptionOverflowError, EncodingError]),
+		stream: true
+	})
+);
+//#endregion
+//#region src/server/client.ts
+const make = RpcClient.make(Api);
+const layer = (url) => RpcClient.layerProtocolSocket().pipe(Layer.provide(NodeSocket.layerWebSocket(url)), Layer.provide(RpcSerialization.layerNdjson));
+/** A server-side failure as the client sees it: the category, not the cause. */
+var ExecutionError = class extends Schema.TaggedError()("Client.ExecutionError", {
+	type: Schema.String,
+	message: Schema.String,
+	status: optional(Schema.Int)
+}) {};
+/**
+* Runs one prompt against a server and renders its output.
+*
+* Sessions are shared, so the stream carries other clients' work too and every
+* terminal event has to be attributed before it is believed. A terminal that
+* arrives before our own prompt is promoted belongs to somebody else's drain:
+* it is remembered rather than raised, and forgotten the moment our prompt is
+* promoted. It only becomes our outcome if the session reaches idle having
+* never promoted us -- at which point it is the best explanation available for
+* why our prompt never ran.
+*/
+const run = Effect.fn("Client.run")(function* (rpc, input, render) {
+	const id = Session.SessionMessageSchema.ID.create();
+	let admitted = false;
+	let promoted = false;
+	let settled = false;
+	let unattributed;
+	const stalled = yield* Deferred.make();
+	const terminal = (event) => {
+		if (Schema.is(EventList.ExecutionInterrupted)(event)) return new ExecutionError({
+			type: "aborted",
+			message: event.data.reason === "shutdown" ? "Server stopped the session" : "Session interrupted"
+		});
+		if (Schema.is(EventList.ExecutionFailed)(event)) return new ExecutionError({
+			type: event.data.error.type,
+			message: event.data.error.message,
+			...event.data.error.status === void 0 ? {} : { status: event.data.error.status }
+		});
+	};
+	const consume = rpc["event.subscribe"]({}).pipe(Stream.mapEffect(Effect.fnUntraced(function* (envelope) {
+		if (envelope.type === Connected.type) {
+			yield* rpc["session.prompt"]({
+				...input,
+				id,
+				delivery: "followUp"
+			});
+			return;
+		}
+		const event = yield* decode(envelope).pipe(Effect.catchTag("UnknownEventTypeError", () => Effect.void));
+		if (event === void 0 || !Predicate.hasProperty(event.data, "sessionId") || event.data.sessionId !== input.sessionId) return;
+		if (Schema.is(EventList.PromptAdmitted)(event) && event.data.messageId === id) admitted = true;
+		if (Schema.is(EventList.Prompted)(event) && event.data.messageId === id) {
+			promoted = true;
+			unattributed = void 0;
+		}
+		if (!admitted) return;
+		const ended = terminal(event);
+		const succeeded = Schema.is(EventList.ExecutionSucceeded)(event);
+		if (!promoted) {
+			if (ended !== void 0) unattributed = ended;
+			if (ended !== void 0 || succeeded) yield* Deferred.succeed(stalled, void 0);
+			return;
+		}
+		if (ended !== void 0) return yield* ended;
+		if (succeeded) {
+			settled = true;
+			return;
+		}
+		yield* render(event);
+	})), Stream.takeUntil(() => settled), Stream.runDrain);
+	let abandoned = false;
+	const reconcile = Deferred.await(stalled).pipe(Effect.andThen(rpc["session.wait"]({ sessionId: input.sessionId })), Effect.andThen(rpc["session.message"]({
+		sessionId: input.sessionId,
+		messageId: id
+	})), Effect.andThen(({ found }) => found ? Effect.never : Effect.sync(() => {
+		abandoned = true;
+	})));
+	yield* Effect.raceFirst(consume, reconcile);
+	if (settled) return;
+	if (abandoned) return yield* unattributed ?? new ExecutionError({
+		type: "unknown",
+		message: "Prompt was not promoted"
+	});
+	return yield* new ExecutionError({
+		type: "transport.disconnected",
+		message: "Event stream ended before the prompt finished; its output was not rendered"
+	});
+});
+//#endregion
+//#region src/cli/output.ts
+const emptyUsage = {
+	turns: 0,
+	input: 0,
+	output: 0,
+	reasoning: 0,
+	cacheRead: 0,
+	cacheWrite: 0,
+	totalTokens: 0,
+	cost: 0
+};
+const addUsage = (summary, message) => ({
+	turns: summary.turns + 1,
+	provider: message.provider.id,
+	model: message.responseModel ?? message.model,
+	input: summary.input + message.usage.input,
+	output: summary.output + message.usage.output,
+	reasoning: summary.reasoning + (message.usage.reasoning ?? 0),
+	cacheRead: summary.cacheRead + message.usage.cacheRead,
+	cacheWrite: summary.cacheWrite + message.usage.cacheWrite,
+	totalTokens: summary.totalTokens + message.usage.totalTokens,
+	cost: summary.cost + message.usage.cost.total
+});
+const number = new Intl.NumberFormat("en-US");
+const row = (label, value) => `${label.padEnd(9)}${value}\n`;
+const formatCost = (cost) => `$${cost.toFixed(cost > 0 && cost < .01 ? 6 : 4)}`;
+const divider = (label, columns = 72) => {
+	const width = Math.min(100, Math.max(32, columns));
+	const start = `── ${label} `;
+	return `${start}${"─".repeat(Math.max(2, width - start.length))}\n`;
+};
+const header = (input) => `${row("session", input.sessionId)}${row("sandbox", `${input.sandbox} · ${input.directory}`)}\n${divider("response", input.columns)}`;
+const usage = (summary, columns) => {
+	const turns = `${summary.turns} ${summary.turns === 1 ? "turn" : "turns"}`;
+	const model = summary.provider === void 0 || summary.model === void 0 ? "unknown" : `${summary.provider}/${summary.model}`;
+	const reasoning = summary.reasoning === 0 ? "" : ` · ${number.format(summary.reasoning)} reasoning`;
+	return `${divider("usage", columns)}${row("model", model)}${row("tokens", `${number.format(summary.input)} input · ${number.format(summary.output)} output${reasoning} · ${number.format(summary.totalTokens)} total`)}${row("cache", `${number.format(summary.cacheRead)} read · ${number.format(summary.cacheWrite)} write`)}${row("cost", `${formatCost(summary.cost)} · ${turns}`)}`;
+};
+const writeOut = (value) => Effect.sync(() => void process.stdout.write(value));
+const writeError = (value) => Effect.sync(() => void process.stderr.write(value));
+const terminalColumns = () => process.stderr.isTTY ? process.stderr.columns ?? 72 : 72;
+//#endregion
+//#region src/cli/error.ts
+/** Bad flag or argument combinations the parser cannot express on its own. */
+var InvalidInputError = class extends Schema.TaggedError()("CLI.InvalidInputError", { message: Schema.String }) {};
+var OAuthError = class extends Schema.TaggedError()("CLI.OAuthError", {
+	message: Schema.String,
+	cause: Schema.optional(Schema.Defect())
+}) {};
+const isInvalidInputError = Schema.is(InvalidInputError);
+const isOAuthError = Schema.is(OAuthError);
+const isProviderError = Schema.is(Runner.ProviderError);
+const isModelCatalogError = Schema.is(Runner.ModelCatalogError);
+const isModelCatalogRefreshError = Schema.is(ModelCatalog.RefreshError);
+const isModelNotFoundError = Schema.is(Runner.ModelNotFoundError);
+const isLLMStreamError = Schema.is(Runner.LLMStreamError);
+const isSandboxProviderError = Schema.is(SandboxProvider.SandboxProviderError);
+const isPluginInstallError = Schema.is(Plugin.InstallError);
+const isPluginSourceError = Schema.is(Plugin.SourceError);
+const isPluginStoreError = Schema.is(Plugin.StoreError);
+const isPluginLoadError = Schema.is(Plugin.LoadError);
+const isSessionNotLinkedError = Schema.is(SessionStore.SessionNotLinkedError);
+const isSettingsError = Schema.is(Settings.SettingsError);
+const isSandboxDriverNotRegisteredError = Schema.is(SandboxError.SandboxDriverNotRegisteredError);
+const isSandboxDriverRegistrationError = Schema.is(SandboxError.SandboxDriverRegistrationError);
+const isExecutionError = Schema.is(ExecutionError);
+const credentialHint = (provider) => {
+	switch (provider) {
+		case "openrouter": return "set OPENROUTER_API_KEY and retry";
+		case "openai": return "set OPENAI_API_KEY and retry";
+		case "openai-codex": return "run `codework auth login --openai-codex` and retry";
+		case "github-copilot": return "run `codework auth login --github-copilot` and retry";
+		case "anthropic": return "set ANTHROPIC_API_KEY and retry";
+		case "google": return "set GOOGLE_GENERATIVE_AI_API_KEY and retry";
+		case "xai": return "set XAI_API_KEY and retry";
+		default: return `configure credentials for provider "${provider}" and retry`;
+	}
+};
+const providerHint = (error) => {
+	switch (error.reason._tag) {
+		case "Runner.ProviderAuthenticationError": return error.reason.authentication === "missing" ? credentialHint(error.provider) : `check the credentials configured for provider "${error.provider}"`;
+		case "Runner.ProviderAuthorizationError": return "check that the credential can access this model and endpoint";
+		case "Runner.ProviderModelUnavailableError": return "check the provider model ID and whether your account can access it";
+		case "Runner.ProviderRateLimitError": return error.reason.retryAfter === void 0 ? "retry after the provider rate-limit window resets" : `retry in about ${Math.ceil(Duration.toMillis(error.reason.retryAfter) / 1e3)} seconds`;
+		case "Runner.ProviderQuotaError": return "check the provider account quota or billing balance";
+		case "Runner.ProviderTimeoutError":
+		case "Runner.ProviderTransportError":
+		case "Runner.ProviderUnavailableError": return error.isRetryable ? "this failure is retryable" : void 0;
+		default: return;
+	}
+};
+const unknownMessage = (error) => {
+	if (error instanceof Error && error.message.trim().length > 0) return error.message;
+	if (typeof error === "string" && error.trim().length > 0) return error;
+	if (typeof error === "object" && error !== null && "_tag" in error) return String(error._tag);
+	return "the command failed for an unknown reason";
+};
+/**
+* What the reader can do about a reference that failed to prepare. A plugin list is
+* usually hand-written in a settings file, so the phase is worth translating.
+*/
+/** One hint per reason. Lowercase, like everything else a plugin failure prints. */
+const providerCategory = (reason) => {
+	switch (reason._tag) {
+		case "Runner.ProviderAuthenticationError": return "provider-authentication-error";
+		case "Runner.ProviderConfigurationError": return "provider-configuration-error";
+		case "Runner.ProviderAuthorizationError": return "provider-authorization-error";
+		case "Runner.ProviderModelUnavailableError": return "provider-model-unavailable-error";
+		case "Runner.ProviderRateLimitError": return "provider-rate-limit-error";
+		case "Runner.ProviderQuotaError": return "provider-quota-error";
+		case "Runner.ProviderInvalidRequestError": return "provider-invalid-request-error";
+		case "Runner.ProviderContentPolicyError": return "provider-content-filter-error";
+		case "Runner.ProviderTimeoutError": return "provider-timeout-error";
+		case "Runner.ProviderTransportError": return "provider-transport-error";
+		case "Runner.ProviderUnavailableError": return "provider-unavailable-error";
+		case "Runner.ProviderInvalidResponseError": return "provider-invalid-response-error";
+		case "Runner.ProviderUnknownError": return "provider-unknown-error";
+	}
+};
+const pluginReasonHint = (reason) => {
+	switch (reason) {
+		case "plugin-unsupported-source": return "a path entry starts with `./`, `../`, `~/` or `/`; anything else is a package or a git spec, and a remote tarball is not supported";
+		case "plugin-not-found": return "the path does not exist; check the spelling, remembering it anchors to the settings file that declares it";
+		case "plugin-escapes-root": return "a plugin path must stay inside the project it is declared in";
+		case "plugin-resolve-failed": return "check that the registry or git remote is reachable, and that your credentials are current";
+		case "plugin-fetch-failed": return "check the package name and version, and that the registry is reachable";
+		case "plugin-no-commit": return "the git source installed but no commit could be recovered; name a branch, tag or commit explicitly";
+		case "plugin-no-entrypoint": return "the package installed but exports no module to import; check its `exports` and `main`";
+		case "plugin-not-installed": return "run `codework plugin install` to fetch what the settings files name";
+		case "plugin-lock-timeout": return "another install is holding this entry; wait for it to finish, or remove the stale `.lock` directory";
+		case "plugin-marker-invalid":
+		case "plugin-index-invalid": return "the store entry is damaged; remove it and install again";
+		case "plugin-collect-failed": return "the store could not be tidied; check the permissions on the plugin cache";
+		case "plugin-import-failed": return "the module failed to load; import it directly to see its own error";
+		case "plugin-missing-dependency": return "the plugin's own dependencies are missing; install them where the plugin lives";
+		case "plugin-not-compiled": return "a plugin installed from git or npm must ship compiled javascript; build it and commit or publish the output";
+		case "plugin-invalid-definition": return "a plugin module must default-export one object with a `setup` and a `vendor.domain.name` id";
+	}
+};
+const settingsHint = (reason) => {
+	switch (reason) {
+		case "read": return "the file exists but could not be read; check that it is a file and readable";
+		case "parse": return "the file is not valid JSON; the location above is where parsing stopped";
+		case "decode": return "the key above holds a value this setting does not accept";
+	}
+};
+/** Render typed SDK errors for humans without exposing Effect causes or provider payloads. */
+const renderError = (error) => {
+	if (isSandboxDriverNotRegisteredError(error)) return `error: sandbox driver "${error.driver}" is not registered (available: ${error.registered?.join(", ") ?? "none"})\n`;
+	if (isSandboxDriverRegistrationError(error)) return `error: ${error.reason}\n`;
+	if (isInvalidInputError(error)) return `error: ${error.message}\n`;
+	if (isOAuthError(error)) return [`error[oauth-credential-error]: ${error.message}`, ...error.cause === void 0 ? [] : [`detail: ${unknownMessage(error.cause)}`]].join("\n") + "\n";
+	if (isSandboxProviderError(error)) return [
+		`error: SandboxProviderError - ${error.sanitized.message}`,
+		`driver: ${error.driver}`,
+		`operation: ${error.operation}`,
+		...error.sanitized.code === void 0 ? [] : [`code: ${error.sanitized.code}`],
+		...error.stack === void 0 ? [] : ["traceback:", error.stack]
+	].join("\n") + "\n";
+	if (isSessionNotLinkedError(error)) return [
+		`error[${error.reason}]: ${error.message}`,
+		`session: ${error.sessionId}`,
+		"hint: run `codework session link <session-id>` from the directory to anchor it to"
+	].join("\n") + "\n";
+	if (isSettingsError(error)) return [
+		`error[settings-${error.reason}-failed]: ${error.path}`,
+		`detail: ${error.detail}`,
+		`hint: ${settingsHint(error.reason)}`
+	].join("\n") + "\n";
+	if (isPluginSourceError(error) || isPluginInstallError(error) || isPluginStoreError(error) || isPluginLoadError(error)) return [
+		`error[${error.reason}]: ${error.message}`,
+		...error.reference === "" ? [] : [`reference: ${error.reference}`],
+		...error.file === void 0 ? [] : [`declared in: ${error.file}`],
+		...isPluginLoadError(error) && error.id !== void 0 ? [`id: ${error.id}`] : [],
+		`hint: ${pluginReasonHint(error.reason)}`
+	].join("\n") + "\n";
+	if (isProviderError(error)) {
+		const hint = providerHint(error);
+		return [
+			`error[${providerCategory(error.reason)}]: ${error.message}`,
+			`provider: ${error.provider}`,
+			`model: ${error.model}`,
+			...error.reason.requestId === void 0 ? [] : [`request: ${error.reason.requestId}`],
+			...hint === void 0 ? [] : [`hint: ${hint}`]
+		].join("\n") + "\n";
+	}
+	if (isModelCatalogError(error)) return [`error[model-catalog-${error.reason}]: ${error.message}`, "hint: run `codework models refresh`"].join("\n") + "\n";
+	if (isModelCatalogRefreshError(error)) return [`error[catalog-refresh-failed]: ${error.message}`, "hint: check the network connection and retry"].join("\n") + "\n";
+	if (isModelNotFoundError(error)) return [`error[model-not-found-error]: ${error.message}`, "hint: check the provider/model IDs in models.gen.json or regenerate the catalog"].join("\n") + "\n";
+	if (isLLMStreamError(error)) return `error[llm-stream-error]: ${error.message}\n`;
+	if (isExecutionError(error)) return [error.type === "aborted" ? `error: ${error.message}` : `error[${error.type}]: ${error.message}`, ...error.status === void 0 ? [] : [`status: ${error.status}`]].join("\n") + "\n";
+	return `error: ${unknownMessage(error)}\n`;
+};
+const reportFailure = (error) => writeError(renderError(error)).pipe(Effect.andThen(Effect.sync(() => {
+	process.exitCode = 1;
+})));
+//#endregion
+export { Connected as _, addUsage as a, terminalColumns as c, writeOut as d, layer as f, OAuthError$1 as g, Api as h, reportFailure as i, usage as l, run as m, OAuthError as n, emptyUsage as o, make as p, renderError as r, header as s, InvalidInputError as t, writeError as u, Core as v, encode as y };
+
+//# sourceMappingURL=error-CxoEKg-4.mjs.map