@botiverse/raft-computer 0.0.62 → 0.0.64

package/dist/lib/index.d.ts

@@ -493,6 +493,36 @@ type MigrationDetection = {
     kind: "server-unavailable";
 };
 
+type ComputerTraceSurface = "server" | "daemon" | "web" | "computer";
+type ComputerTraceSpanKind = "server" | "client" | "internal" | "producer" | "consumer";
+type ComputerTraceStatus = "ok" | "error" | "cancelled";
+type ComputerTraceAttributes = Record<string, unknown>;
+type ComputerTraceClientSource = "daemon" | "computer.cli" | "computer.menu-bar";
+interface ComputerTraceContext {
+    traceId: string;
+    spanId: string;
+    parentSpanId: string | null;
+    traceFlags: string;
+}
+interface ComputerStartSpanOptions {
+    parent?: ComputerTraceContext | null;
+    surface: ComputerTraceSurface;
+    kind?: ComputerTraceSpanKind;
+    attrs?: ComputerTraceAttributes;
+    startTimeMs?: number;
+}
+interface ComputerEndSpanOptions {
+    attrs?: ComputerTraceAttributes;
+}
+interface ComputerActiveSpan {
+    readonly context: ComputerTraceContext;
+    addEvent(name: string, attrs?: ComputerTraceAttributes): void;
+    end(status?: ComputerTraceStatus, options?: ComputerEndSpanOptions): void;
+}
+interface ComputerTracer {
+    startSpan(name: string, options: ComputerStartSpanOptions): ComputerActiveSpan;
+}
+
 type ComputerApiEvent = {
     kind: "login.device-code";
     verifyUrl: string;
@@ -1423,47 +1453,24 @@ interface ComputerApi {
  * IPC-vs-disk decision: when a service is running, mutations route through it
  * via IPC so the supervisor's in-memory runner state stays consistent; when no
  * service is up (cold boot) the disk-only lib-pure handlers apply directly.
- */
-declare function createComputerApi(slockHome: string): ComputerApi;
-
-/**
- * One Computer trace line. INTENTIONALLY shaped as `@slock-ai/shared`'s
- * canonical `TraceEvent` (`{ name, timeMs, attrs? }`) so the forthcoming shared
- * trace-client can route these through the real `Tracer` / `TraceSink` with ZERO
- * format reconciliation. We MIRROR the shape rather than import the type — that
- * keeps this interim file sink from pulling `@slock-ai/shared` into the Computer
- * package early; the shared-client work (B) replaces this helper's internals
- * (file-append → `Tracer.startSpan` + `TraceSink.record`) while the emitted
- * shape stays identical.
  *
- * `attrs` is the open structured bag (== shared `TraceAttributes`): route
- * decisions carry `{ method, decision }`, the menu-bar action trail carries
- * `{ kind, durationMs, outcome, errorCode }`, etc.
+ * The single-writer ops (reset / upgrade routing) are spanned through the
+ * caller-injected `opts.tracer` (default `noopTracer`, so untraced callers /
+ * tests are zero-side-effect). The CALLER owns `source` attribution — the CLI
+ * injects a `computer.cli` trace-client, the menu-bar a `computer.menu-bar`
+ * one — so the same lib code attributes correctly across both surfaces.
  */
-interface ComputerTraceEvent {
-    /** event name, e.g. "route-decision" | "action" */
-    name: string;
-    /** epoch milliseconds (== shared `TraceEvent.timeMs`) */
-    timeMs: number;
-    /** structured attributes (== shared `TraceAttributes`) */
-    attrs?: Record<string, unknown>;
-}
-/**
- * Best-effort append of one `ComputerTraceEvent` JSON line to the Computer trace
- * sink (`run/trace.jsonl`). NEVER throws or blocks the traced operation — any fs
- * error is swallowed.
- */
-declare function traceEvent(slockHome: string, event: ComputerTraceEvent): Promise<void>;
+declare function createComputerApi(slockHome: string, opts?: {
+    tracer?: ComputerTracer;
+}): ComputerApi;
+
 /**
- * Record a single-writer route decision (reset / upgrade routing) as a
- * `route-decision` `ComputerTraceEvent` — the answer to "did this op take the
- * EXPECTED route" (`via-service` | `via-disk` | `ipc` | `standalone`).
+ * Build the env-gated Computer trace client for a given emitting `source`
+ * (CLI vs menu-bar). Both surfaces share this so their spans land in the same
+ * `<computerDir>/traces/` sink with consistent gating. `SLOCK_COMPUTER_LOCAL_TRACE=0`
+ * disables (default on, mirrors the daemon); any setup failure falls back to noop.
  */
-declare function recordRouteDecision(slockHome: string, opts: {
-    method: string;
-    decision: string;
-    timeMs?: number;
-}): Promise<void>;
+declare function createComputerTracer(slockHome: string, source: ComputerTraceClientSource): ComputerTracer;
 
 /**
  * Read the Computer-level aggregate status from `installRoot`. Identical
@@ -1509,4 +1516,4 @@ declare function userSessionPath(slockHome: string): string;
 
 declare const COMPUTER_VERSION: string;
 
-export { type AttachInput, type AttachResult, COMPUTER_VERSION, type ComputerApi, type ComputerApiEvent, ComputerError, ComputerServiceError, type ComputerStatusReport, type ComputerTraceEvent, type ConnectService, type ConnectServiceOptions, DEFAULT_UPGRADE_BASE_URL, type DaemonState, IPC_ERROR_CODES, type IpcErrorCode, type LegacyMachineCandidate, type LegacyMachineRosterClient, type LegacyMachineRosterEntry, type LegacyMachineRosterResult, LegacyMachinesClient, type ListRunnersResult, type LoginInput, type LoginResult, MIGRATION_DETECTION_KINDS, MIGRATION_FRESH_TRIGGERS, type ManualPathValidation, type MigrationDetection, type MigrationDetectionKind, type MigrationFreshTrigger, type PickerSelection, RUNNER_STATE_VALUES, type RequestMethodMap, type RequestOptions, type ResetRunnerResult, type ResetServiceResult, type RunnerListItem as RunnerInfo, type RunnerListPerServer, type RunnerState, type RunnerStatusResult, SERVICE_STATE_VALUES, STATE_READER_ERROR_CODES, type ServerHealth, type ServerStatusRow, ServersClient, type ServiceClient, ServiceClientError, type ServiceEvent, type ServiceState, type ServiceStatusResult, StateReaderError, type StateReaderErrorCode, UPGRADE_ERROR_CODES, type UpgradeBundle, type UpgradeErrorCode, type UpgradeLogEntry, type UpgradeLogEntryErr, type UpgradeLogEntryOk, type UpgradeStartResult, type UpgradeTrigger, type UserServerEntry, type UserServersResult, assertUpgradeLogEntry, connectService, createComputerApi, detectLegacyMigration, fetchCdnLatestVersion, isComputerError, isIpcErrorCode, isMigrationDetectionKind, isRunnerState, isServiceState, listRunners, pickMigrationCandidateFromInput, readRunnerStatus, readServiceStatus, recordRouteDecision, traceEvent, userSessionPath, validateManualMigratePath };
+export { type AttachInput, type AttachResult, COMPUTER_VERSION, type ComputerActiveSpan, type ComputerApi, type ComputerApiEvent, type ComputerEndSpanOptions, ComputerError, ComputerServiceError, type ComputerStartSpanOptions, type ComputerStatusReport, type ComputerTraceAttributes, type ComputerTraceClientSource, type ComputerTraceContext, type ComputerTraceSpanKind, type ComputerTraceStatus, type ComputerTraceSurface, type ComputerTracer, type ConnectService, type ConnectServiceOptions, DEFAULT_UPGRADE_BASE_URL, type DaemonState, IPC_ERROR_CODES, type IpcErrorCode, type LegacyMachineCandidate, type LegacyMachineRosterClient, type LegacyMachineRosterEntry, type LegacyMachineRosterResult, LegacyMachinesClient, type ListRunnersResult, type LoginInput, type LoginResult, MIGRATION_DETECTION_KINDS, MIGRATION_FRESH_TRIGGERS, type ManualPathValidation, type MigrationDetection, type MigrationDetectionKind, type MigrationFreshTrigger, type PickerSelection, RUNNER_STATE_VALUES, type RequestMethodMap, type RequestOptions, type ResetRunnerResult, type ResetServiceResult, type RunnerListItem as RunnerInfo, type RunnerListPerServer, type RunnerState, type RunnerStatusResult, SERVICE_STATE_VALUES, STATE_READER_ERROR_CODES, type ServerHealth, type ServerStatusRow, ServersClient, type ServiceClient, ServiceClientError, type ServiceEvent, type ServiceState, type ServiceStatusResult, StateReaderError, type StateReaderErrorCode, UPGRADE_ERROR_CODES, type UpgradeBundle, type UpgradeErrorCode, type UpgradeLogEntry, type UpgradeLogEntryErr, type UpgradeLogEntryOk, type UpgradeStartResult, type UpgradeTrigger, type UserServerEntry, type UserServersResult, assertUpgradeLogEntry, connectService, createComputerApi, createComputerTracer, detectLegacyMigration, fetchCdnLatestVersion, isComputerError, isIpcErrorCode, isMigrationDetectionKind, isRunnerState, isServiceState, listRunners, pickMigrationCandidateFromInput, readRunnerStatus, readServiceStatus, userSessionPath, validateManualMigratePath };