@quantiya/codevibe-core 2.0.0 → 2.0.1

package/dist/orchestration-shell/cli.d.ts

@@ -0,0 +1,96 @@
+import { AppSyncClient } from '../appsync';
+import { Session } from '../types';
+import { type ShellEventEmit } from './emit-shell-event';
+import { BackendPlannerClient, PlannerCacheLayer, PlannerHealthMachine } from '../planner';
+import type { PlannerAdapter, PlannerInput, PlannerDecision, PlannerProbeResult } from '../planner/adapter';
+/**
+ * CP-1.b IMPL r5 H-1 — Sentinel error thrown by the stub-session
+ * planner adapter. `handleShellUserInput` catches this typed class and
+ * routes it through the explicit error renderer (SLASH_OUTPUT) so the
+ * user sees an actionable message in the conversation pane instead of
+ * a silent log line. Stub sessions (sessionId prefix `cp1a-local-` or
+ * empty `encryptedKeys`) cannot reach the Lambda — `encryptedKeys` is
+ * missing, the keychain resolver returns null, and the planner client
+ * throws "session key unresolved" deep inside classify(). Surfacing
+ * that as a typed error at the adapter boundary is cleaner than the
+ * generic Error from `BackendPlannerClient.classify()`.
+ */
+export declare class PlannerUnavailableError extends Error {
+    constructor(msg: string);
+}
+/**
+ * CP-1.b IMPL r5 H-1 — Stub-session planner adapter.
+ *
+ * CP-1.a still ships a fake `cp1a-local-*` session with no
+ * `encryptedKeys[]`. The production `BackendPlannerClient` cannot
+ * classify against that session — the Lambda requires E2E-encrypted
+ * payloads, which requires the session key, which the keychain
+ * resolver cannot derive without `encryptedKeys`.
+ *
+ * Rather than wire up the production stack and let it fail with a
+ * generic "session key unresolved" Error deep inside classify(), we
+ * detect stub sessions at bootstrap and construct this adapter, which
+ * throws a typed `PlannerUnavailableError` on classify(). The shell's
+ * `handleShellUserInput` catches this and renders an actionable
+ * message to the user (`PLANNER_UNAVAILABLE: <reason>`). CP-1.c lands
+ * the real session bootstrap (resumeOrCreateSession + AppSync) and
+ * this adapter is no longer wired in.
+ */
+export declare class PlannerUnavailableAdapter implements PlannerAdapter {
+    private readonly reason;
+    private activeSessionId;
+    constructor(reason: string);
+    classify(_input: PlannerInput): Promise<PlannerDecision>;
+    probe(): Promise<PlannerProbeResult>;
+    setActiveSession(sessionId: string | null): void;
+}
+/**
+ * CP-1.b IMPL r5 H-1 — Detect a CP-1.a stub session. Two signals:
+ *   (a) `sessionId` starts with `cp1a-local-` (the
+ *       `buildStubSession()` prefix).
+ *   (b) `session.encryptedKeys` is empty / missing (any session
+ *       lacking E2E keys cannot route through the Lambda).
+ *
+ * Either signal triggers the stub-session adapter. The (b) gate is
+ * a defensive fallback for the case where CP-1.c starts a real
+ * session bootstrap but `prepareSessionEncryption()` returns null
+ * (no device keys registered): the planner is genuinely unavailable
+ * until the user registers a device key.
+ */
+export declare function isStubSession(session: Session): boolean;
+export declare function main(argv: string[]): Promise<number>;
+/**
+ * CP-1.b IMPL r4 H-1 — Production planner stack factory.
+ *
+ * Builds the full BackendPlannerClient + PlannerCacheLayer +
+ * PlannerHealthMachine chain so the orchestration shell can call
+ * `plannerAdapter.classify()` on natural-language input.
+ *
+ * Co-located with the CLI bootstrap (NOT inside `runOrchestrationShell`)
+ * because the shell accepts an injected adapter for tests; the
+ * production bootstrap site is the single canonical instantiation
+ * point.
+ *
+ * Exported for unit tests; production callers go through `main()`.
+ */
+export declare function buildProductionPlannerStack(appsyncClient: AppSyncClient, emitter: (args: ShellEventEmit) => Promise<void>): {
+    adapter: BackendPlannerClient;
+    cache: PlannerCacheLayer;
+    health: PlannerHealthMachine;
+};
+import { HookBridge } from '../local-executor/hook-bridge';
+export interface BridgeRefusalArgs {
+    refusedMessageId: string;
+    shellContent: string;
+    shellMetadata?: Record<string, unknown>;
+}
+/**
+ * Wrap any async operation that may throw `AuthorityError`; on refusal, emit
+ * the two-channel refusal pair (LOCK #C4-3) via the supplied HookBridge and
+ * re-throw. Non-AuthorityError exceptions propagate unchanged.
+ *
+ * The HookBridge passed in MUST be the same instance the orchestration shell
+ * uses for plugin-hook ingestion — both paths share the audit-before-shell
+ * ordering invariant via the bridge's `bridgeAuthorityRefusal` method.
+ */
+export declare function bridgeAuthorityErrorToShellRefusal<T>(bridge: HookBridge, refusalArgs: BridgeRefusalArgs, fn: () => Promise<T>): Promise<T>;