@codeam/shared 2.76.16 → 2.76.18

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+import { z } from 'zod';
+
 /**
  * Protocol-level types for TUI chrome steps and interactive selectors.
  *
@@ -1502,6 +1504,22 @@ interface PreviewScriptCandidate {
 }
 type PreviewState = 'idle' | 'detection_pending' | 'detection_ready' | 'starting' | 'running' | 'error';
 type PreviewErrorStage = 'detection' | 'spawn' | 'tunnel' | 'ready_timeout' | 'unsupported';
+/**
+ * Machine-readable code on a `preview_error`, for errors the apps route to a
+ * specific action instead of "Try again". `CREDITS_EXHAUSTED` = the managed
+ * agent's detect one-shot was refused by our agent-proxy with a 402 (prepaid
+ * wallet at 0) — the apps open top-up; a retry would hit the same 402.
+ * Additive: older CLIs omit it.
+ */
+type PreviewErrorCode = 'CREDITS_EXHAUSTED';
+/**
+ * WHY a `stage: 'detection'` / `'unsupported'` preview_error happened —
+ * telemetry only (`preview_lifecycle.error_reason`), never user copy, never
+ * the agent's raw output. Each value has a different fix, which is the point:
+ * five unexplained detection failures in a row (codeagent-qrk1) could not be
+ * told apart.
+ */
+type PreviewErrorReason = 'empty_project' | 'no_oneshot' | 'timeout' | 'no_output' | 'no_json' | 'missing_fields' | 'provider_credits' | 'credits_exhausted' | 'unsupported';
 /**
  * Un servicio que el proyecto necesita y que NO pudimos levantarle.
  *
@@ -1543,6 +1561,7 @@ interface PreviewStatus {
     error?: {
         stage: PreviewErrorStage;
         message: string;
+        code?: PreviewErrorCode;
     };
     /**
      * Servicios que el proyecto pide y no estan sirviendo.
@@ -2182,6 +2201,46 @@ type ScratchExportResult = {
     }>;
 };
 
+/**
+ * Session blocker — a TYPED tag on the terminal chat bubble of a turn that
+ * cannot run ("you're out of credits", "Cursor needs a paid plan", …).
+ *
+ * The bubble itself stays prose (every client renders it as markdown). This
+ * tag rides NEXT to it on the `{type:'text', done:true}` output chunk as
+ * `blocker`, so mobile/web can attach the right escape-route buttons from the
+ * kind instead of regex-matching the CLI's wording — which drifted silently:
+ * the apps matched "reached your daily CodeAgent Cloud limit" while the CLI
+ * had long been saying "You’ve reached today’s agent usage limit", so the
+ * CLI-built house-limit bubble never got its buttons (codeagent-gfip).
+ *
+ * CANONICAL WIRE OWNER: this file. The apps keep their regex only as the
+ * fallback for chunks from CLIs that predate the tag.
+ */
+declare const SESSION_BLOCKER_KINDS: readonly ["house_agent_limit", "house_agent_unavailable", "agent_plan_required", "agent_auth_failed", "credits_exhausted", "provider_credits_exhausted", "agent_startup_failed"];
+type SessionBlockerKind = (typeof SESSION_BLOCKER_KINDS)[number];
+interface SessionBlocker {
+    kind: SessionBlockerKind;
+    /** Agent the blocker is about (registry id or label), when known. */
+    agentId?: string;
+    /** Provider name for `provider_credits_exhausted` (e.g. `OpenRouter`). */
+    provider?: string;
+}
+declare const SessionBlockerSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        credits_exhausted: "credits_exhausted";
+        house_agent_limit: "house_agent_limit";
+        house_agent_unavailable: "house_agent_unavailable";
+        agent_plan_required: "agent_plan_required";
+        agent_auth_failed: "agent_auth_failed";
+        provider_credits_exhausted: "provider_credits_exhausted";
+        agent_startup_failed: "agent_startup_failed";
+    }>;
+    agentId: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Validate an untrusted `blocker` field off the wire; `null` when absent or malformed. */
+declare function toSessionBlocker(raw: unknown): SessionBlocker | null;
+
 /**
  * Prompt the CLI sends to the user's linked agent (Claude, Codex, …)
  * in a headless one-shot to detect how to start the project's dev
@@ -2194,4 +2253,44 @@ type ScratchExportResult = {
  */
 declare const PREVIEW_DETECT_PROMPT: string;
 
-export { AGENT_REGISTRY, AGENT_STANDARD_BLOCK, AGENT_STANDARD_MARKER, AGENT_STANDARD_TEXT, type AgentAuth, type AgentAuthKind, type AgentId, type AgentMetadata, type AgentMode, type AgentModel, type AgentReviewFinding, type AgentReviewPlan, type AgentReviewReport, type AnswerResolvedEvent, type AwaitingAnswerEvent, type AwaitingAnswerOption, type BeadsActionCommand, type BeadsActionKind, type BeadsActionPayload, type BeadsActionRequest, type BeadsActionType, type BeadsConfigureAction, type BeadsDependencyDto, type BeadsDependencyKind, type BeadsIngestPayload, type BeadsIssueDto, type BeadsIssueStatus, type BeadsMemoryDto, type BeadsProjectDto, type BeadsProvisioningPayload, type BeadsProvisioningStatus, type BeadsSnapshotDto, type BeadsStatus, type BeadsStatusState, type BeadsStatusSummary, type BlameLineWire, type BrokeredIntegrationToken, CODER_PROMPT, type ChromeStep, type ChromeToolType, type CommitEntryWire, DEFAULT_API_BASE_URL, DEFAULT_GUARDRAIL_POLICY, DEPLOY_CHOICE_ORDER, DEP_TO_INTEGRATION, DEV_API_BASE_URL, type DeployChoice, type DerivedCredentialSource, type EnvVar, type FileBlameEvent, type FileChangeStatus, type FileChangedEvent, type FileHistoryEvent, type FileReviewStatus, GUARDRAIL_CATEGORIES, GUARDRAIL_CATEGORY_META, GUARDRAIL_CONFIGURE_COMMAND, GUARDRAIL_DISPOSITIONS, type GuardrailCategory, type GuardrailCategoryMeta, type GuardrailDisposition, type GuardrailPolicy, HANDOFF_FENCE_TAG, HEARTBEAT_INTERVAL_MS_DEFAULT, HOUSE_AGENT_ID, HOUSE_AGENT_NAME, HOUSE_AGENT_PROVIDER, HOUSE_AGENT_SUBTITLE, HOUSE_AGENT_VENDOR, type HandoffProposal, type HandoffResolution, type HunkLineType, INSTALL_SNIPPETS, INTEGRATION_BRANDING, INTEGRATION_REGISTRY, INTERNAL_TO_PUBLIC, type InputSuggestionChunk, type IntegrationApiKeyField, type IntegrationAuthKind, type IntegrationBranding, type IntegrationCategory, type IntegrationDefinition, type IntegrationDelivery, type IntegrationHealth, type IntegrationId, type IntegrationMcpDelivery, type IntegrationStatus, type IntegrationsManifest, type IntegrationsManifestEntry, LINKED_AGENT_IDS, type LinkedAgentId, MANAGED_AGENT_ENV, MANAGED_AGENT_SUBTITLE, MANAGED_PROVIDER_DISPLAY_NAMES, MANAGED_PROVIDER_IDS, MAX_PACK_FINDINGS, MODEL_CONTEXT_WINDOW, MODEL_PRICING, type ManagedProviderId, type MissingService, type ModelPricing, type NormalizedMessage, OBSERVER_BRIDGE_PORT, PACK_ACTION_COMMAND, PACK_FINDINGS_FILE, PACK_HANDOFF_HEADING, PACK_REGISTRY, PACK_START_COMMAND, PACK_STATUS_COMMAND, PACK_WORKFLOW_ARTICLE, PREVIEW_DETECT_PROMPT, PROTOCOL_VERSION, PUBLIC_TO_INTERNAL, type PackActionKind, type PackActionPayload, type PackDefinition, type PackFinding, type PackFindingResolution, type PackFindingSeverity, type PackFindingsParseResult, type PackHandoffRecord, type PackId, type PackPendingControl, type PackRunState, type PackRunStatus, type PackStageDef, type PackStageState, type PackStageStatus, type PackStartPayload, type ParsedPackFindings, type PendingReviewHunkEvent, type PendingReviewHunkLine, type PrCheck, type PrRef, type PrReviewEntry, type PrReviewVerdict, type PreviewAgentHighlight, type PreviewDetection, type PreviewErrorStage, type PreviewOrigin, type PreviewScriptCandidate, type PreviewState, type PreviewStatus, type PullRequestDetail, type PullRequestSummary, QA_PROMPT, REVIEWER_PROMPT, type RemoteCommand, type RepoStack, type RepoStackDetection, SCRATCH_STARTER_PROMPTS, SCRATCH_ZIP_FREE_LIMIT_BYTES, SCRATCH_ZIP_WIFI_HINT_BYTES, SKILL_REGISTRY, SPECIFIER_PROMPT, SQUAD_CONFIGURE_COMMAND, SQUAD_HOP_BUDGET_DEFAULT, SQUAD_HOP_BUDGET_MAX, SQUAD_HOP_BUDGET_MIN, SQUAD_SPECIALTIES, SQUAD_STATS_COMMAND, SSE_SOCKET_TIMEOUT_MS, STACK_TO_RECOMMENDED, SWITCH_AGENT_COMMAND, type ScratchExportResult, type ScratchProjectState, type ScratchSavedVia, type SelectPrompt, type SkillDefinition, type SkillDelivery, type SkillFileDelivery, type SkillId, type SkillRail, type SkillsManifest, type SkillsManifestEntry, type SquadAutoConfig, type SquadConfigurePayload, type SquadConfigureResult, type SquadMemberActivity, type SquadRosterAgent, type SquadRosterData, type SquadStatsResult, type StartTaskFailedResult, type StartTaskPayload, type StarterPrompt, type StreamingChunkEvent, type StreamingChunkKind, type SwitchAgentCommand, type SwitchAgentResult, type SwitchAgentStatus, type SwitchAgentStep, TERMINAL_AGENT_PREFIX, UNKNOWN_MODEL_PRICING, UPCOMING_INTEGRATION_IDS, USER_EVENTS, type UserEventName, clampHopBudget, classifyStack, detectedIntegrationsFromDeps, extractHandoffSection, getAgent, getContextWindow, getEnabledAgents, getEnabledIntegrations, getIntegration, getIntegrationBranding, getIntegrationsByCategory, getPackDefinition, getPricing, getSkillDefinition, installableAgentIds, internalToPublic, isGuardrailDisposition, isKnownAgentId, isKnownIntegrationId, isKnownModel, isLinkedAgentId, isManagedProviderId, isNoopInstallSnippet, isPackId, isSkillId, normalizeAgentId, normalizeGuardrailPolicy, orderDeployChoices, parsePackFindings, publicToInternal, recommendForDeps, renderToLines, resolveApiBaseUrl, skillHasRail, toRemoteCommand, tryGetContextWindow };
+/**
+ * The agents report — `POST /api/plugin/agents` (plugin → backend) and
+ * `GET /api/plugin/agents?pluginId=` (app → backend).
+ *
+ * CANONICAL WIRE OWNER: this file (`@codeam/shared`), per the cross-repo rule.
+ * The backend stores each entry verbatim and hands it back to the app.
+ */
+/**
+ * Whether the reported agent can actually answer a prompt on this host.
+ *
+ * WHY (codeagent-04jp, 2026-10-02): a local session whose agent could not run
+ * (Claude Code not signed in on the user's computer) read "The host isn't
+ * responding" in the app — the only signal was silence. The plugin now says
+ * what it knows, so the app can offer the real fix ("sign in on your computer"
+ * or "use CodeAgent credits instead").
+ *
+ * - `ready`         — the agent started and accepted a session.
+ * - `not_installed` — the agent's binary/adapter is missing on the host.
+ * - `not_signed_in` — the agent is installed but has no usable login/key.
+ * - `failed`        — it was installed and signed in, and still failed to start.
+ *
+ * Optional on the wire: older plugins never send it, and its absence means
+ * "unknown", never `ready`.
+ */
+declare const PLUGIN_AGENT_STATUSES: readonly ["ready", "not_installed", "not_signed_in", "failed"];
+type PluginAgentStatus = (typeof PLUGIN_AGENT_STATUSES)[number];
+declare function isPluginAgentStatus(x: unknown): x is PluginAgentStatus;
+/** One entry of the agents report. */
+interface PluginAgentReport {
+    /** Runtime agent id (`claude`, `codex`, …) — NOT the public linked id. */
+    id: string;
+    name: string;
+    /** Icon key — the apps key their logo map by agent id. */
+    icon: string;
+    installed: boolean;
+    isTerminal?: boolean;
+    /** See {@link PluginAgentStatus}. Absent = unknown (older plugin). */
+    status?: PluginAgentStatus;
+}
+
+export { AGENT_REGISTRY, AGENT_STANDARD_BLOCK, AGENT_STANDARD_MARKER, AGENT_STANDARD_TEXT, type AgentAuth, type AgentAuthKind, type AgentId, type AgentMetadata, type AgentMode, type AgentModel, type AgentReviewFinding, type AgentReviewPlan, type AgentReviewReport, type AnswerResolvedEvent, type AwaitingAnswerEvent, type AwaitingAnswerOption, type BeadsActionCommand, type BeadsActionKind, type BeadsActionPayload, type BeadsActionRequest, type BeadsActionType, type BeadsConfigureAction, type BeadsDependencyDto, type BeadsDependencyKind, type BeadsIngestPayload, type BeadsIssueDto, type BeadsIssueStatus, type BeadsMemoryDto, type BeadsProjectDto, type BeadsProvisioningPayload, type BeadsProvisioningStatus, type BeadsSnapshotDto, type BeadsStatus, type BeadsStatusState, type BeadsStatusSummary, type BlameLineWire, type BrokeredIntegrationToken, CODER_PROMPT, type ChromeStep, type ChromeToolType, type CommitEntryWire, DEFAULT_API_BASE_URL, DEFAULT_GUARDRAIL_POLICY, DEPLOY_CHOICE_ORDER, DEP_TO_INTEGRATION, DEV_API_BASE_URL, type DeployChoice, type DerivedCredentialSource, type EnvVar, type FileBlameEvent, type FileChangeStatus, type FileChangedEvent, type FileHistoryEvent, type FileReviewStatus, GUARDRAIL_CATEGORIES, GUARDRAIL_CATEGORY_META, GUARDRAIL_CONFIGURE_COMMAND, GUARDRAIL_DISPOSITIONS, type GuardrailCategory, type GuardrailCategoryMeta, type GuardrailDisposition, type GuardrailPolicy, HANDOFF_FENCE_TAG, HEARTBEAT_INTERVAL_MS_DEFAULT, HOUSE_AGENT_ID, HOUSE_AGENT_NAME, HOUSE_AGENT_PROVIDER, HOUSE_AGENT_SUBTITLE, HOUSE_AGENT_VENDOR, type HandoffProposal, type HandoffResolution, type HunkLineType, INSTALL_SNIPPETS, INTEGRATION_BRANDING, INTEGRATION_REGISTRY, INTERNAL_TO_PUBLIC, type InputSuggestionChunk, type IntegrationApiKeyField, type IntegrationAuthKind, type IntegrationBranding, type IntegrationCategory, type IntegrationDefinition, type IntegrationDelivery, type IntegrationHealth, type IntegrationId, type IntegrationMcpDelivery, type IntegrationStatus, type IntegrationsManifest, type IntegrationsManifestEntry, LINKED_AGENT_IDS, type LinkedAgentId, MANAGED_AGENT_ENV, MANAGED_AGENT_SUBTITLE, MANAGED_PROVIDER_DISPLAY_NAMES, MANAGED_PROVIDER_IDS, MAX_PACK_FINDINGS, MODEL_CONTEXT_WINDOW, MODEL_PRICING, type ManagedProviderId, type MissingService, type ModelPricing, type NormalizedMessage, OBSERVER_BRIDGE_PORT, PACK_ACTION_COMMAND, PACK_FINDINGS_FILE, PACK_HANDOFF_HEADING, PACK_REGISTRY, PACK_START_COMMAND, PACK_STATUS_COMMAND, PACK_WORKFLOW_ARTICLE, PLUGIN_AGENT_STATUSES, PREVIEW_DETECT_PROMPT, PROTOCOL_VERSION, PUBLIC_TO_INTERNAL, type PackActionKind, type PackActionPayload, type PackDefinition, type PackFinding, type PackFindingResolution, type PackFindingSeverity, type PackFindingsParseResult, type PackHandoffRecord, type PackId, type PackPendingControl, type PackRunState, type PackRunStatus, type PackStageDef, type PackStageState, type PackStageStatus, type PackStartPayload, type ParsedPackFindings, type PendingReviewHunkEvent, type PendingReviewHunkLine, type PluginAgentReport, type PluginAgentStatus, type PrCheck, type PrRef, type PrReviewEntry, type PrReviewVerdict, type PreviewAgentHighlight, type PreviewDetection, type PreviewErrorCode, type PreviewErrorReason, type PreviewErrorStage, type PreviewOrigin, type PreviewScriptCandidate, type PreviewState, type PreviewStatus, type PullRequestDetail, type PullRequestSummary, QA_PROMPT, REVIEWER_PROMPT, type RemoteCommand, type RepoStack, type RepoStackDetection, SCRATCH_STARTER_PROMPTS, SCRATCH_ZIP_FREE_LIMIT_BYTES, SCRATCH_ZIP_WIFI_HINT_BYTES, SESSION_BLOCKER_KINDS, SKILL_REGISTRY, SPECIFIER_PROMPT, SQUAD_CONFIGURE_COMMAND, SQUAD_HOP_BUDGET_DEFAULT, SQUAD_HOP_BUDGET_MAX, SQUAD_HOP_BUDGET_MIN, SQUAD_SPECIALTIES, SQUAD_STATS_COMMAND, SSE_SOCKET_TIMEOUT_MS, STACK_TO_RECOMMENDED, SWITCH_AGENT_COMMAND, type ScratchExportResult, type ScratchProjectState, type ScratchSavedVia, type SelectPrompt, type SessionBlocker, type SessionBlockerKind, SessionBlockerSchema, type SkillDefinition, type SkillDelivery, type SkillFileDelivery, type SkillId, type SkillRail, type SkillsManifest, type SkillsManifestEntry, type SquadAutoConfig, type SquadConfigurePayload, type SquadConfigureResult, type SquadMemberActivity, type SquadRosterAgent, type SquadRosterData, type SquadStatsResult, type StartTaskFailedResult, type StartTaskPayload, type StarterPrompt, type StreamingChunkEvent, type StreamingChunkKind, type SwitchAgentCommand, type SwitchAgentResult, type SwitchAgentStatus, type SwitchAgentStep, TERMINAL_AGENT_PREFIX, UNKNOWN_MODEL_PRICING, UPCOMING_INTEGRATION_IDS, USER_EVENTS, type UserEventName, clampHopBudget, classifyStack, detectedIntegrationsFromDeps, extractHandoffSection, getAgent, getContextWindow, getEnabledAgents, getEnabledIntegrations, getIntegration, getIntegrationBranding, getIntegrationsByCategory, getPackDefinition, getPricing, getSkillDefinition, installableAgentIds, internalToPublic, isGuardrailDisposition, isKnownAgentId, isKnownIntegrationId, isKnownModel, isLinkedAgentId, isManagedProviderId, isNoopInstallSnippet, isPackId, isPluginAgentStatus, isSkillId, normalizeAgentId, normalizeGuardrailPolicy, orderDeployChoices, parsePackFindings, publicToInternal, recommendForDeps, renderToLines, resolveApiBaseUrl, skillHasRail, toRemoteCommand, toSessionBlocker, tryGetContextWindow };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { z } from 'zod';
+
 /**
  * Protocol-level types for TUI chrome steps and interactive selectors.
  *
@@ -1502,6 +1504,22 @@ interface PreviewScriptCandidate {
 }
 type PreviewState = 'idle' | 'detection_pending' | 'detection_ready' | 'starting' | 'running' | 'error';
 type PreviewErrorStage = 'detection' | 'spawn' | 'tunnel' | 'ready_timeout' | 'unsupported';
+/**
+ * Machine-readable code on a `preview_error`, for errors the apps route to a
+ * specific action instead of "Try again". `CREDITS_EXHAUSTED` = the managed
+ * agent's detect one-shot was refused by our agent-proxy with a 402 (prepaid
+ * wallet at 0) — the apps open top-up; a retry would hit the same 402.
+ * Additive: older CLIs omit it.
+ */
+type PreviewErrorCode = 'CREDITS_EXHAUSTED';
+/**
+ * WHY a `stage: 'detection'` / `'unsupported'` preview_error happened —
+ * telemetry only (`preview_lifecycle.error_reason`), never user copy, never
+ * the agent's raw output. Each value has a different fix, which is the point:
+ * five unexplained detection failures in a row (codeagent-qrk1) could not be
+ * told apart.
+ */
+type PreviewErrorReason = 'empty_project' | 'no_oneshot' | 'timeout' | 'no_output' | 'no_json' | 'missing_fields' | 'provider_credits' | 'credits_exhausted' | 'unsupported';
 /**
  * Un servicio que el proyecto necesita y que NO pudimos levantarle.
  *
@@ -1543,6 +1561,7 @@ interface PreviewStatus {
     error?: {
         stage: PreviewErrorStage;
         message: string;
+        code?: PreviewErrorCode;
     };
     /**
      * Servicios que el proyecto pide y no estan sirviendo.
@@ -2182,6 +2201,46 @@ type ScratchExportResult = {
     }>;
 };
 
+/**
+ * Session blocker — a TYPED tag on the terminal chat bubble of a turn that
+ * cannot run ("you're out of credits", "Cursor needs a paid plan", …).
+ *
+ * The bubble itself stays prose (every client renders it as markdown). This
+ * tag rides NEXT to it on the `{type:'text', done:true}` output chunk as
+ * `blocker`, so mobile/web can attach the right escape-route buttons from the
+ * kind instead of regex-matching the CLI's wording — which drifted silently:
+ * the apps matched "reached your daily CodeAgent Cloud limit" while the CLI
+ * had long been saying "You’ve reached today’s agent usage limit", so the
+ * CLI-built house-limit bubble never got its buttons (codeagent-gfip).
+ *
+ * CANONICAL WIRE OWNER: this file. The apps keep their regex only as the
+ * fallback for chunks from CLIs that predate the tag.
+ */
+declare const SESSION_BLOCKER_KINDS: readonly ["house_agent_limit", "house_agent_unavailable", "agent_plan_required", "agent_auth_failed", "credits_exhausted", "provider_credits_exhausted", "agent_startup_failed"];
+type SessionBlockerKind = (typeof SESSION_BLOCKER_KINDS)[number];
+interface SessionBlocker {
+    kind: SessionBlockerKind;
+    /** Agent the blocker is about (registry id or label), when known. */
+    agentId?: string;
+    /** Provider name for `provider_credits_exhausted` (e.g. `OpenRouter`). */
+    provider?: string;
+}
+declare const SessionBlockerSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        credits_exhausted: "credits_exhausted";
+        house_agent_limit: "house_agent_limit";
+        house_agent_unavailable: "house_agent_unavailable";
+        agent_plan_required: "agent_plan_required";
+        agent_auth_failed: "agent_auth_failed";
+        provider_credits_exhausted: "provider_credits_exhausted";
+        agent_startup_failed: "agent_startup_failed";
+    }>;
+    agentId: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Validate an untrusted `blocker` field off the wire; `null` when absent or malformed. */
+declare function toSessionBlocker(raw: unknown): SessionBlocker | null;
+
 /**
  * Prompt the CLI sends to the user's linked agent (Claude, Codex, …)
  * in a headless one-shot to detect how to start the project's dev
@@ -2194,4 +2253,44 @@ type ScratchExportResult = {
  */
 declare const PREVIEW_DETECT_PROMPT: string;
 
-export { AGENT_REGISTRY, AGENT_STANDARD_BLOCK, AGENT_STANDARD_MARKER, AGENT_STANDARD_TEXT, type AgentAuth, type AgentAuthKind, type AgentId, type AgentMetadata, type AgentMode, type AgentModel, type AgentReviewFinding, type AgentReviewPlan, type AgentReviewReport, type AnswerResolvedEvent, type AwaitingAnswerEvent, type AwaitingAnswerOption, type BeadsActionCommand, type BeadsActionKind, type BeadsActionPayload, type BeadsActionRequest, type BeadsActionType, type BeadsConfigureAction, type BeadsDependencyDto, type BeadsDependencyKind, type BeadsIngestPayload, type BeadsIssueDto, type BeadsIssueStatus, type BeadsMemoryDto, type BeadsProjectDto, type BeadsProvisioningPayload, type BeadsProvisioningStatus, type BeadsSnapshotDto, type BeadsStatus, type BeadsStatusState, type BeadsStatusSummary, type BlameLineWire, type BrokeredIntegrationToken, CODER_PROMPT, type ChromeStep, type ChromeToolType, type CommitEntryWire, DEFAULT_API_BASE_URL, DEFAULT_GUARDRAIL_POLICY, DEPLOY_CHOICE_ORDER, DEP_TO_INTEGRATION, DEV_API_BASE_URL, type DeployChoice, type DerivedCredentialSource, type EnvVar, type FileBlameEvent, type FileChangeStatus, type FileChangedEvent, type FileHistoryEvent, type FileReviewStatus, GUARDRAIL_CATEGORIES, GUARDRAIL_CATEGORY_META, GUARDRAIL_CONFIGURE_COMMAND, GUARDRAIL_DISPOSITIONS, type GuardrailCategory, type GuardrailCategoryMeta, type GuardrailDisposition, type GuardrailPolicy, HANDOFF_FENCE_TAG, HEARTBEAT_INTERVAL_MS_DEFAULT, HOUSE_AGENT_ID, HOUSE_AGENT_NAME, HOUSE_AGENT_PROVIDER, HOUSE_AGENT_SUBTITLE, HOUSE_AGENT_VENDOR, type HandoffProposal, type HandoffResolution, type HunkLineType, INSTALL_SNIPPETS, INTEGRATION_BRANDING, INTEGRATION_REGISTRY, INTERNAL_TO_PUBLIC, type InputSuggestionChunk, type IntegrationApiKeyField, type IntegrationAuthKind, type IntegrationBranding, type IntegrationCategory, type IntegrationDefinition, type IntegrationDelivery, type IntegrationHealth, type IntegrationId, type IntegrationMcpDelivery, type IntegrationStatus, type IntegrationsManifest, type IntegrationsManifestEntry, LINKED_AGENT_IDS, type LinkedAgentId, MANAGED_AGENT_ENV, MANAGED_AGENT_SUBTITLE, MANAGED_PROVIDER_DISPLAY_NAMES, MANAGED_PROVIDER_IDS, MAX_PACK_FINDINGS, MODEL_CONTEXT_WINDOW, MODEL_PRICING, type ManagedProviderId, type MissingService, type ModelPricing, type NormalizedMessage, OBSERVER_BRIDGE_PORT, PACK_ACTION_COMMAND, PACK_FINDINGS_FILE, PACK_HANDOFF_HEADING, PACK_REGISTRY, PACK_START_COMMAND, PACK_STATUS_COMMAND, PACK_WORKFLOW_ARTICLE, PREVIEW_DETECT_PROMPT, PROTOCOL_VERSION, PUBLIC_TO_INTERNAL, type PackActionKind, type PackActionPayload, type PackDefinition, type PackFinding, type PackFindingResolution, type PackFindingSeverity, type PackFindingsParseResult, type PackHandoffRecord, type PackId, type PackPendingControl, type PackRunState, type PackRunStatus, type PackStageDef, type PackStageState, type PackStageStatus, type PackStartPayload, type ParsedPackFindings, type PendingReviewHunkEvent, type PendingReviewHunkLine, type PrCheck, type PrRef, type PrReviewEntry, type PrReviewVerdict, type PreviewAgentHighlight, type PreviewDetection, type PreviewErrorStage, type PreviewOrigin, type PreviewScriptCandidate, type PreviewState, type PreviewStatus, type PullRequestDetail, type PullRequestSummary, QA_PROMPT, REVIEWER_PROMPT, type RemoteCommand, type RepoStack, type RepoStackDetection, SCRATCH_STARTER_PROMPTS, SCRATCH_ZIP_FREE_LIMIT_BYTES, SCRATCH_ZIP_WIFI_HINT_BYTES, SKILL_REGISTRY, SPECIFIER_PROMPT, SQUAD_CONFIGURE_COMMAND, SQUAD_HOP_BUDGET_DEFAULT, SQUAD_HOP_BUDGET_MAX, SQUAD_HOP_BUDGET_MIN, SQUAD_SPECIALTIES, SQUAD_STATS_COMMAND, SSE_SOCKET_TIMEOUT_MS, STACK_TO_RECOMMENDED, SWITCH_AGENT_COMMAND, type ScratchExportResult, type ScratchProjectState, type ScratchSavedVia, type SelectPrompt, type SkillDefinition, type SkillDelivery, type SkillFileDelivery, type SkillId, type SkillRail, type SkillsManifest, type SkillsManifestEntry, type SquadAutoConfig, type SquadConfigurePayload, type SquadConfigureResult, type SquadMemberActivity, type SquadRosterAgent, type SquadRosterData, type SquadStatsResult, type StartTaskFailedResult, type StartTaskPayload, type StarterPrompt, type StreamingChunkEvent, type StreamingChunkKind, type SwitchAgentCommand, type SwitchAgentResult, type SwitchAgentStatus, type SwitchAgentStep, TERMINAL_AGENT_PREFIX, UNKNOWN_MODEL_PRICING, UPCOMING_INTEGRATION_IDS, USER_EVENTS, type UserEventName, clampHopBudget, classifyStack, detectedIntegrationsFromDeps, extractHandoffSection, getAgent, getContextWindow, getEnabledAgents, getEnabledIntegrations, getIntegration, getIntegrationBranding, getIntegrationsByCategory, getPackDefinition, getPricing, getSkillDefinition, installableAgentIds, internalToPublic, isGuardrailDisposition, isKnownAgentId, isKnownIntegrationId, isKnownModel, isLinkedAgentId, isManagedProviderId, isNoopInstallSnippet, isPackId, isSkillId, normalizeAgentId, normalizeGuardrailPolicy, orderDeployChoices, parsePackFindings, publicToInternal, recommendForDeps, renderToLines, resolveApiBaseUrl, skillHasRail, toRemoteCommand, tryGetContextWindow };
+/**
+ * The agents report — `POST /api/plugin/agents` (plugin → backend) and
+ * `GET /api/plugin/agents?pluginId=` (app → backend).
+ *
+ * CANONICAL WIRE OWNER: this file (`@codeam/shared`), per the cross-repo rule.
+ * The backend stores each entry verbatim and hands it back to the app.
+ */
+/**
+ * Whether the reported agent can actually answer a prompt on this host.
+ *
+ * WHY (codeagent-04jp, 2026-10-02): a local session whose agent could not run
+ * (Claude Code not signed in on the user's computer) read "The host isn't
+ * responding" in the app — the only signal was silence. The plugin now says
+ * what it knows, so the app can offer the real fix ("sign in on your computer"
+ * or "use CodeAgent credits instead").
+ *
+ * - `ready`         — the agent started and accepted a session.
+ * - `not_installed` — the agent's binary/adapter is missing on the host.
+ * - `not_signed_in` — the agent is installed but has no usable login/key.
+ * - `failed`        — it was installed and signed in, and still failed to start.
+ *
+ * Optional on the wire: older plugins never send it, and its absence means
+ * "unknown", never `ready`.
+ */
+declare const PLUGIN_AGENT_STATUSES: readonly ["ready", "not_installed", "not_signed_in", "failed"];
+type PluginAgentStatus = (typeof PLUGIN_AGENT_STATUSES)[number];
+declare function isPluginAgentStatus(x: unknown): x is PluginAgentStatus;
+/** One entry of the agents report. */
+interface PluginAgentReport {
+    /** Runtime agent id (`claude`, `codex`, …) — NOT the public linked id. */
+    id: string;
+    name: string;
+    /** Icon key — the apps key their logo map by agent id. */
+    icon: string;
+    installed: boolean;
+    isTerminal?: boolean;
+    /** See {@link PluginAgentStatus}. Absent = unknown (older plugin). */
+    status?: PluginAgentStatus;
+}
+
+export { AGENT_REGISTRY, AGENT_STANDARD_BLOCK, AGENT_STANDARD_MARKER, AGENT_STANDARD_TEXT, type AgentAuth, type AgentAuthKind, type AgentId, type AgentMetadata, type AgentMode, type AgentModel, type AgentReviewFinding, type AgentReviewPlan, type AgentReviewReport, type AnswerResolvedEvent, type AwaitingAnswerEvent, type AwaitingAnswerOption, type BeadsActionCommand, type BeadsActionKind, type BeadsActionPayload, type BeadsActionRequest, type BeadsActionType, type BeadsConfigureAction, type BeadsDependencyDto, type BeadsDependencyKind, type BeadsIngestPayload, type BeadsIssueDto, type BeadsIssueStatus, type BeadsMemoryDto, type BeadsProjectDto, type BeadsProvisioningPayload, type BeadsProvisioningStatus, type BeadsSnapshotDto, type BeadsStatus, type BeadsStatusState, type BeadsStatusSummary, type BlameLineWire, type BrokeredIntegrationToken, CODER_PROMPT, type ChromeStep, type ChromeToolType, type CommitEntryWire, DEFAULT_API_BASE_URL, DEFAULT_GUARDRAIL_POLICY, DEPLOY_CHOICE_ORDER, DEP_TO_INTEGRATION, DEV_API_BASE_URL, type DeployChoice, type DerivedCredentialSource, type EnvVar, type FileBlameEvent, type FileChangeStatus, type FileChangedEvent, type FileHistoryEvent, type FileReviewStatus, GUARDRAIL_CATEGORIES, GUARDRAIL_CATEGORY_META, GUARDRAIL_CONFIGURE_COMMAND, GUARDRAIL_DISPOSITIONS, type GuardrailCategory, type GuardrailCategoryMeta, type GuardrailDisposition, type GuardrailPolicy, HANDOFF_FENCE_TAG, HEARTBEAT_INTERVAL_MS_DEFAULT, HOUSE_AGENT_ID, HOUSE_AGENT_NAME, HOUSE_AGENT_PROVIDER, HOUSE_AGENT_SUBTITLE, HOUSE_AGENT_VENDOR, type HandoffProposal, type HandoffResolution, type HunkLineType, INSTALL_SNIPPETS, INTEGRATION_BRANDING, INTEGRATION_REGISTRY, INTERNAL_TO_PUBLIC, type InputSuggestionChunk, type IntegrationApiKeyField, type IntegrationAuthKind, type IntegrationBranding, type IntegrationCategory, type IntegrationDefinition, type IntegrationDelivery, type IntegrationHealth, type IntegrationId, type IntegrationMcpDelivery, type IntegrationStatus, type IntegrationsManifest, type IntegrationsManifestEntry, LINKED_AGENT_IDS, type LinkedAgentId, MANAGED_AGENT_ENV, MANAGED_AGENT_SUBTITLE, MANAGED_PROVIDER_DISPLAY_NAMES, MANAGED_PROVIDER_IDS, MAX_PACK_FINDINGS, MODEL_CONTEXT_WINDOW, MODEL_PRICING, type ManagedProviderId, type MissingService, type ModelPricing, type NormalizedMessage, OBSERVER_BRIDGE_PORT, PACK_ACTION_COMMAND, PACK_FINDINGS_FILE, PACK_HANDOFF_HEADING, PACK_REGISTRY, PACK_START_COMMAND, PACK_STATUS_COMMAND, PACK_WORKFLOW_ARTICLE, PLUGIN_AGENT_STATUSES, PREVIEW_DETECT_PROMPT, PROTOCOL_VERSION, PUBLIC_TO_INTERNAL, type PackActionKind, type PackActionPayload, type PackDefinition, type PackFinding, type PackFindingResolution, type PackFindingSeverity, type PackFindingsParseResult, type PackHandoffRecord, type PackId, type PackPendingControl, type PackRunState, type PackRunStatus, type PackStageDef, type PackStageState, type PackStageStatus, type PackStartPayload, type ParsedPackFindings, type PendingReviewHunkEvent, type PendingReviewHunkLine, type PluginAgentReport, type PluginAgentStatus, type PrCheck, type PrRef, type PrReviewEntry, type PrReviewVerdict, type PreviewAgentHighlight, type PreviewDetection, type PreviewErrorCode, type PreviewErrorReason, type PreviewErrorStage, type PreviewOrigin, type PreviewScriptCandidate, type PreviewState, type PreviewStatus, type PullRequestDetail, type PullRequestSummary, QA_PROMPT, REVIEWER_PROMPT, type RemoteCommand, type RepoStack, type RepoStackDetection, SCRATCH_STARTER_PROMPTS, SCRATCH_ZIP_FREE_LIMIT_BYTES, SCRATCH_ZIP_WIFI_HINT_BYTES, SESSION_BLOCKER_KINDS, SKILL_REGISTRY, SPECIFIER_PROMPT, SQUAD_CONFIGURE_COMMAND, SQUAD_HOP_BUDGET_DEFAULT, SQUAD_HOP_BUDGET_MAX, SQUAD_HOP_BUDGET_MIN, SQUAD_SPECIALTIES, SQUAD_STATS_COMMAND, SSE_SOCKET_TIMEOUT_MS, STACK_TO_RECOMMENDED, SWITCH_AGENT_COMMAND, type ScratchExportResult, type ScratchProjectState, type ScratchSavedVia, type SelectPrompt, type SessionBlocker, type SessionBlockerKind, SessionBlockerSchema, type SkillDefinition, type SkillDelivery, type SkillFileDelivery, type SkillId, type SkillRail, type SkillsManifest, type SkillsManifestEntry, type SquadAutoConfig, type SquadConfigurePayload, type SquadConfigureResult, type SquadMemberActivity, type SquadRosterAgent, type SquadRosterData, type SquadStatsResult, type StartTaskFailedResult, type StartTaskPayload, type StarterPrompt, type StreamingChunkEvent, type StreamingChunkKind, type SwitchAgentCommand, type SwitchAgentResult, type SwitchAgentStatus, type SwitchAgentStep, TERMINAL_AGENT_PREFIX, UNKNOWN_MODEL_PRICING, UPCOMING_INTEGRATION_IDS, USER_EVENTS, type UserEventName, clampHopBudget, classifyStack, detectedIntegrationsFromDeps, extractHandoffSection, getAgent, getContextWindow, getEnabledAgents, getEnabledIntegrations, getIntegration, getIntegrationBranding, getIntegrationsByCategory, getPackDefinition, getPricing, getSkillDefinition, installableAgentIds, internalToPublic, isGuardrailDisposition, isKnownAgentId, isKnownIntegrationId, isKnownModel, isLinkedAgentId, isManagedProviderId, isNoopInstallSnippet, isPackId, isPluginAgentStatus, isSkillId, normalizeAgentId, normalizeGuardrailPolicy, orderDeployChoices, parsePackFindings, publicToInternal, recommendForDeps, renderToLines, resolveApiBaseUrl, skillHasRail, toRemoteCommand, toSessionBlocker, tryGetContextWindow };

package/dist/index.js

@@ -61,6 +61,7 @@ __export(index_exports, {
   PACK_START_COMMAND: () => PACK_START_COMMAND,
   PACK_STATUS_COMMAND: () => PACK_STATUS_COMMAND,
   PACK_WORKFLOW_ARTICLE: () => PACK_WORKFLOW_ARTICLE,
+  PLUGIN_AGENT_STATUSES: () => PLUGIN_AGENT_STATUSES,
   PREVIEW_DETECT_PROMPT: () => PREVIEW_DETECT_PROMPT,
   PROTOCOL_VERSION: () => PROTOCOL_VERSION,
   PUBLIC_TO_INTERNAL: () => PUBLIC_TO_INTERNAL,
@@ -69,6 +70,7 @@ __export(index_exports, {
   SCRATCH_STARTER_PROMPTS: () => SCRATCH_STARTER_PROMPTS,
   SCRATCH_ZIP_FREE_LIMIT_BYTES: () => SCRATCH_ZIP_FREE_LIMIT_BYTES,
   SCRATCH_ZIP_WIFI_HINT_BYTES: () => SCRATCH_ZIP_WIFI_HINT_BYTES,
+  SESSION_BLOCKER_KINDS: () => SESSION_BLOCKER_KINDS,
   SKILL_REGISTRY: () => SKILL_REGISTRY,
   SPECIFIER_PROMPT: () => SPECIFIER_PROMPT,
   SQUAD_CONFIGURE_COMMAND: () => SQUAD_CONFIGURE_COMMAND,
@@ -80,6 +82,7 @@ __export(index_exports, {
   SSE_SOCKET_TIMEOUT_MS: () => SSE_SOCKET_TIMEOUT_MS,
   STACK_TO_RECOMMENDED: () => STACK_TO_RECOMMENDED,
   SWITCH_AGENT_COMMAND: () => SWITCH_AGENT_COMMAND,
+  SessionBlockerSchema: () => SessionBlockerSchema,
   TERMINAL_AGENT_PREFIX: () => TERMINAL_AGENT_PREFIX,
   UNKNOWN_MODEL_PRICING: () => UNKNOWN_MODEL_PRICING,
   UPCOMING_INTEGRATION_IDS: () => UPCOMING_INTEGRATION_IDS,
@@ -108,6 +111,7 @@ __export(index_exports, {
   isManagedProviderId: () => isManagedProviderId,
   isNoopInstallSnippet: () => isNoopInstallSnippet,
   isPackId: () => isPackId,
+  isPluginAgentStatus: () => isPluginAgentStatus,
   isSkillId: () => isSkillId,
   normalizeAgentId: () => normalizeAgentId,
   normalizeGuardrailPolicy: () => normalizeGuardrailPolicy,
@@ -119,6 +123,7 @@ __export(index_exports, {
   resolveApiBaseUrl: () => resolveApiBaseUrl,
   skillHasRail: () => skillHasRail,
   toRemoteCommand: () => toRemoteCommand,
+  toSessionBlocker: () => toSessionBlocker,
   tryGetContextWindow: () => tryGetContextWindow
 });
 module.exports = __toCommonJS(index_exports);
@@ -3226,6 +3231,34 @@ var SCRATCH_STARTER_PROMPTS = [
 var SCRATCH_ZIP_FREE_LIMIT_BYTES = 104857600;
 var SCRATCH_ZIP_WIFI_HINT_BYTES = 209715200;
 
+// src/types/session-blocker.ts
+var import_zod2 = require("zod");
+var SESSION_BLOCKER_KINDS = [
+  /** CodeAgent Cloud usage ceiling — PRO lifts it. */
+  "house_agent_limit",
+  /** CodeAgent Cloud down on OUR side — nothing to buy. */
+  "house_agent_unavailable",
+  /** The vendor (e.g. Cursor) needs a paid plan to run its agent. */
+  "agent_plan_required",
+  /** The user's own agent credentials are invalid/expired. */
+  "agent_auth_failed",
+  /** The prepaid CodeAgent wallet is empty. */
+  "credits_exhausted",
+  /** The user's OWN provider key (OpenRouter, …) has no balance. */
+  "provider_credits_exhausted",
+  /** The agent process died before it could open a session. */
+  "agent_startup_failed"
+];
+var SessionBlockerSchema = import_zod2.z.object({
+  kind: import_zod2.z.enum(SESSION_BLOCKER_KINDS),
+  agentId: import_zod2.z.string().min(1).max(64).optional(),
+  provider: import_zod2.z.string().min(1).max(120).optional()
+});
+function toSessionBlocker(raw) {
+  const parsed = SessionBlockerSchema.safeParse(raw);
+  return parsed.success ? parsed.data : null;
+}
+
 // src/preview-prompts.ts
 var PREVIEW_DETECT_PROMPT = `
 Analyze the project in the current working directory and return how to start
@@ -3272,6 +3305,12 @@ CRITICAL \u2014 setup_commands:
 
 OUTPUT JSON ONLY. NO MARKDOWN. NO COMMENTARY.
 `.trim();
+
+// src/types/plugin-agents.ts
+var PLUGIN_AGENT_STATUSES = ["ready", "not_installed", "not_signed_in", "failed"];
+function isPluginAgentStatus(x) {
+  return typeof x === "string" && PLUGIN_AGENT_STATUSES.includes(x);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AGENT_REGISTRY,
@@ -3315,6 +3354,7 @@ OUTPUT JSON ONLY. NO MARKDOWN. NO COMMENTARY.
   PACK_START_COMMAND,
   PACK_STATUS_COMMAND,
   PACK_WORKFLOW_ARTICLE,
+  PLUGIN_AGENT_STATUSES,
   PREVIEW_DETECT_PROMPT,
   PROTOCOL_VERSION,
   PUBLIC_TO_INTERNAL,
@@ -3323,6 +3363,7 @@ OUTPUT JSON ONLY. NO MARKDOWN. NO COMMENTARY.
   SCRATCH_STARTER_PROMPTS,
   SCRATCH_ZIP_FREE_LIMIT_BYTES,
   SCRATCH_ZIP_WIFI_HINT_BYTES,
+  SESSION_BLOCKER_KINDS,
   SKILL_REGISTRY,
   SPECIFIER_PROMPT,
   SQUAD_CONFIGURE_COMMAND,
@@ -3334,6 +3375,7 @@ OUTPUT JSON ONLY. NO MARKDOWN. NO COMMENTARY.
   SSE_SOCKET_TIMEOUT_MS,
   STACK_TO_RECOMMENDED,
   SWITCH_AGENT_COMMAND,
+  SessionBlockerSchema,
   TERMINAL_AGENT_PREFIX,
   UNKNOWN_MODEL_PRICING,
   UPCOMING_INTEGRATION_IDS,
@@ -3362,6 +3404,7 @@ OUTPUT JSON ONLY. NO MARKDOWN. NO COMMENTARY.
   isManagedProviderId,
   isNoopInstallSnippet,
   isPackId,
+  isPluginAgentStatus,
   isSkillId,
   normalizeAgentId,
   normalizeGuardrailPolicy,
@@ -3373,6 +3416,7 @@ OUTPUT JSON ONLY. NO MARKDOWN. NO COMMENTARY.
   resolveApiBaseUrl,
   skillHasRail,
   toRemoteCommand,
+  toSessionBlocker,
   tryGetContextWindow
 });
 //# sourceMappingURL=index.js.map