@zakstam/codex-local-component 0.7.0 → 0.8.0

package/LLMS.md

@@ -2,6 +2,14 @@
 
 Canonical default: runtime-owned host integration (`dispatchManaged: false`).
 
+## Actor Scope Contract
+
+- Actor payload is `actor: { userId?: string }`.
+- `userId` is optional:
+- when present, data access is scoped to that user.
+- when omitted, data access is scoped to anonymous-only rows.
+- Do not send tenant/device identifiers.
+
 ## Hard Rule
 
 - Follow this file as the only default implementation strategy.
@@ -29,21 +37,52 @@ app.use(codexLocal);
 export default app;
 ```
 
-3. Generate host surfaces from the canonical manifest.
+3. Generate Convex app types once before host wiring.
+
+```bash
+npx convex dev --once
+```
+
+- Required so app-generated `./_generated/api` and `./_generated/server` exist and stay authoritative.
+
+4. Generate host surfaces from the canonical manifest.
 
 ```bash
 pnpm run host:generate
 ```
 
-4. Keep host files in this split:
+5. Keep host files in this split:
 
 - `convex/chat.generated.ts`: generated preset wrappers (do not edit)
 - `convex/chat.extensions.ts`: app-owned custom endpoints
 - `convex/chat.ts`: stable entrypoint (`export *` from generated + extensions)
 
-5. Use runtime-owned host preset behavior only.
+6. Use runtime-owned host preset behavior only.
 
 - Generated wrappers are based on `defineRuntimeOwnedHostSlice(...)`.
+- Construct runtime with explicit persistence wiring:
+
+```ts
+import { createCodexHostRuntime } from "@zakstam/codex-local-component/host";
+
+const runtime = createCodexHostRuntime({
+  persistence: {
+    ensureThread,
+    ensureSession,
+    ingestSafe,
+    upsertPendingServerRequest,
+    resolvePendingServerRequest,
+    listPendingServerRequests,
+    enqueueTurnDispatch,
+    claimNextTurnDispatch,
+    markTurnDispatchStarted,
+    markTurnDispatchCompleted,
+    markTurnDispatchFailed,
+    cancelTurnDispatch,
+  },
+});
+```
+
 - Runtime startup must be explicit runtime-owned:
 
 ```ts
@@ -55,16 +94,16 @@ await runtime.start({
 });
 ```
 
-6. Start turns through `runtime.sendTurn(text)`.
+7. Start turns through `runtime.sendTurn(text)`.
 
 - Do not call `startClaimedTurn` in the canonical path.
 
-7. Validate host wiring during startup.
+8. Validate host wiring during startup.
 
 - Query `chat.validateHostWiring` once at process boot.
 - Fail fast if `ok` is `false`.
 
-8. Use canonical host query/mutation endpoints in React hooks.
+9. Use canonical host query/mutation endpoints in React hooks.
 
 - `useCodexMessages` -> `chat.listThreadMessagesForHooks`
 - `useCodexTurn` -> `chat.listTurnMessagesForHooks`
@@ -80,6 +119,13 @@ pnpm run host:generate
 pnpm run host:check
 ```
 
+If your app does not define monorepo wrappers, run local equivalents:
+
+```bash
+pnpm run generate:host-surfaces
+pnpm run check:host-surfaces
+```
+
 From each host app:
 
 ```bash
@@ -88,6 +134,8 @@ pnpm run wiring:smoke
 pnpm run typecheck
 ```
 
+If your app does not define `wiring:smoke`, run the check inline with `ConvexHttpClient` against `chat.validateHostWiring`.
+
 ## Required Host Surface Ownership
 
 - Generated surface owns preset endpoint exports.

package/dist/component/_generated/api.d.ts

@@ -9,9 +9,30 @@
 import type * as approvals from "../approvals.js";
 import type * as dispatch from "../dispatch.js";
 import type * as index from "../index.js";
+import type * as ingest_applyApprovals from "../ingest/applyApprovals.js";
+import type * as ingest_applyMessages from "../ingest/applyMessages.js";
+import type * as ingest_applyStreams from "../ingest/applyStreams.js";
+import type * as ingest_applyTurns from "../ingest/applyTurns.js";
+import type * as ingest_checkpoints from "../ingest/checkpoints.js";
+import type * as ingest_index from "../ingest/index.js";
+import type * as ingest_normalize from "../ingest/normalize.js";
+import type * as ingest_postIngest from "../ingest/postIngest.js";
+import type * as ingest_sessionGuard from "../ingest/sessionGuard.js";
+import type * as ingest_stateCache from "../ingest/stateCache.js";
+import type * as ingest_types from "../ingest/types.js";
+import type * as messages from "../messages.js";
+import type * as pagination from "../pagination.js";
+import type * as reasoning from "../reasoning.js";
+import type * as scope from "../scope.js";
+import type * as serverRequests from "../serverRequests.js";
 import type * as sessions from "../sessions.js";
+import type * as streamStats from "../streamStats.js";
 import type * as streams from "../streams.js";
 import type * as sync from "../sync.js";
+import type * as syncHelpers from "../syncHelpers.js";
+import type * as syncIngest from "../syncIngest.js";
+import type * as syncReplay from "../syncReplay.js";
+import type * as syncRuntime from "../syncRuntime.js";
 import type * as threads from "../threads.js";
 import type * as turns from "../turns.js";
 import type * as turnsInternal from "../turnsInternal.js";
@@ -22,9 +43,30 @@ declare const fullApi: ApiFromModules<{
     approvals: typeof approvals;
     dispatch: typeof dispatch;
     index: typeof index;
+    "ingest/applyApprovals": typeof ingest_applyApprovals;
+    "ingest/applyMessages": typeof ingest_applyMessages;
+    "ingest/applyStreams": typeof ingest_applyStreams;
+    "ingest/applyTurns": typeof ingest_applyTurns;
+    "ingest/checkpoints": typeof ingest_checkpoints;
+    "ingest/index": typeof ingest_index;
+    "ingest/normalize": typeof ingest_normalize;
+    "ingest/postIngest": typeof ingest_postIngest;
+    "ingest/sessionGuard": typeof ingest_sessionGuard;
+    "ingest/stateCache": typeof ingest_stateCache;
+    "ingest/types": typeof ingest_types;
+    messages: typeof messages;
+    pagination: typeof pagination;
+    reasoning: typeof reasoning;
+    scope: typeof scope;
+    serverRequests: typeof serverRequests;
     sessions: typeof sessions;
+    streamStats: typeof streamStats;
     streams: typeof streams;
     sync: typeof sync;
+    syncHelpers: typeof syncHelpers;
+    syncIngest: typeof syncIngest;
+    syncReplay: typeof syncReplay;
+    syncRuntime: typeof syncRuntime;
     threads: typeof threads;
     turns: typeof turns;
     turnsInternal: typeof turnsInternal;

package/dist/component/_generated/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/component/_generated/api.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,KAAK,KAAK,SAAS,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,KAAK,KAAK,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,KAAK,OAAO,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,KAAK,IAAI,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,KAAK,OAAO,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,KAAK,KAAK,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,KAAK,aAAa,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,KAAK,KAAK,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,KAAK,KAAK,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EACT,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAGvB,QAAA,MAAM,OAAO,EAAE,cAAc,CAAC;IAC5B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,OAAO,EAAE,OAAO,OAAO,CAAC;IACxB,IAAI,EAAE,OAAO,IAAI,CAAC;IAClB,OAAO,EAAE,OAAO,OAAO,CAAC;IACxB,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,KAAK,EAAE,OAAO,KAAK,CAAC;CACrB,CAAiB,CAAC;AAEnB;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG,EAAE,SAAS,CACzB,OAAO,OAAO,EACd,iBAAiB,CAAC,GAAG,EAAE,QAAQ,CAAC,CACjB,CAAC;AAElB;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,SAAS,CAC9B,OAAO,OAAO,EACd,iBAAiB,CAAC,GAAG,EAAE,UAAU,CAAC,CACnB,CAAC;AAElB,eAAO,MAAM,UAAU,EAAqC,EAAE,CAAC"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/component/_generated/api.ts"],"names":[],"mappings":"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"}

package/dist/component/_generated/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../src/component/_generated/api.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB;;;;;;;GAOG;AAmBH,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE1D,MAAM,OAAO,GAYR,MAAa,CAAC;AAEnB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,GAAG,GAGZ,MAAa,CAAC;AAElB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAGjB,MAAa,CAAC;AAElB,MAAM,CAAC,MAAM,UAAU,GAAG,iBAAiB,EAAmB,CAAC"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../src/component/_generated/api.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB;;;;;;;GAOG;AAwCH,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE1D,MAAM,OAAO,GAiCR,MAAa,CAAC;AAEnB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,GAAG,GAGZ,MAAa,CAAC;AAElB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAGjB,MAAa,CAAC;AAElB,MAAM,CAAC,MAAM,UAAU,GAAG,iBAAiB,EAAmB,CAAC"}