@zakstam/codex-local-component 0.6.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/LLMS.md +111 -0
  2. package/README.md +25 -249
  3. package/dist/component/_generated/api.d.ts +42 -0
  4. package/dist/component/_generated/api.d.ts.map +1 -1
  5. package/dist/component/_generated/api.js.map +1 -1
  6. package/dist/component/_generated/component.d.ts +279 -126
  7. package/dist/component/_generated/component.d.ts.map +1 -1
  8. package/dist/component/approvals.d.ts +2 -6
  9. package/dist/component/approvals.d.ts.map +1 -1
  10. package/dist/component/approvals.js +8 -7
  11. package/dist/component/approvals.js.map +1 -1
  12. package/dist/component/dispatch.d.ts +7 -21
  13. package/dist/component/dispatch.d.ts.map +1 -1
  14. package/dist/component/dispatch.js +21 -20
  15. package/dist/component/dispatch.js.map +1 -1
  16. package/dist/component/ingest/applyApprovals.d.ts.map +1 -1
  17. package/dist/component/ingest/applyApprovals.js +3 -2
  18. package/dist/component/ingest/applyApprovals.js.map +1 -1
  19. package/dist/component/ingest/applyMessages.d.ts.map +1 -1
  20. package/dist/component/ingest/applyMessages.js +8 -7
  21. package/dist/component/ingest/applyMessages.js.map +1 -1
  22. package/dist/component/ingest/applyStreams.d.ts.map +1 -1
  23. package/dist/component/ingest/applyStreams.js +13 -12
  24. package/dist/component/ingest/applyStreams.js.map +1 -1
  25. package/dist/component/ingest/applyTurns.d.ts.map +1 -1
  26. package/dist/component/ingest/applyTurns.js +8 -7
  27. package/dist/component/ingest/applyTurns.js.map +1 -1
  28. package/dist/component/ingest/checkpoints.d.ts.map +1 -1
  29. package/dist/component/ingest/checkpoints.js +10 -13
  30. package/dist/component/ingest/checkpoints.js.map +1 -1
  31. package/dist/component/ingest/index.d.ts.map +1 -1
  32. package/dist/component/ingest/index.js +3 -2
  33. package/dist/component/ingest/index.js.map +1 -1
  34. package/dist/component/ingest/postIngest.d.ts.map +1 -1
  35. package/dist/component/ingest/postIngest.js +2 -1
  36. package/dist/component/ingest/postIngest.js.map +1 -1
  37. package/dist/component/ingest/sessionGuard.d.ts.map +1 -1
  38. package/dist/component/ingest/sessionGuard.js +5 -14
  39. package/dist/component/ingest/sessionGuard.js.map +1 -1
  40. package/dist/component/ingest/stateCache.d.ts +1 -1
  41. package/dist/component/ingest/stateCache.d.ts.map +1 -1
  42. package/dist/component/ingest/stateCache.js +8 -8
  43. package/dist/component/ingest/stateCache.js.map +1 -1
  44. package/dist/component/ingest/types.d.ts +2 -4
  45. package/dist/component/ingest/types.d.ts.map +1 -1
  46. package/dist/component/messages.d.ts +2 -6
  47. package/dist/component/messages.d.ts.map +1 -1
  48. package/dist/component/messages.js +4 -3
  49. package/dist/component/messages.js.map +1 -1
  50. package/dist/component/reasoning.d.ts +1 -3
  51. package/dist/component/reasoning.d.ts.map +1 -1
  52. package/dist/component/reasoning.js +3 -2
  53. package/dist/component/reasoning.js.map +1 -1
  54. package/dist/component/schema.d.ts +116 -122
  55. package/dist/component/schema.d.ts.map +1 -1
  56. package/dist/component/schema.js +74 -78
  57. package/dist/component/schema.js.map +1 -1
  58. package/dist/component/scope.d.ts +4 -0
  59. package/dist/component/scope.d.ts.map +1 -0
  60. package/dist/component/scope.js +6 -0
  61. package/dist/component/scope.js.map +1 -0
  62. package/dist/component/serverRequests.d.ts +3 -9
  63. package/dist/component/serverRequests.d.ts.map +1 -1
  64. package/dist/component/serverRequests.js +11 -10
  65. package/dist/component/serverRequests.js.map +1 -1
  66. package/dist/component/sessions.d.ts +1 -1
  67. package/dist/component/sessions.js +3 -3
  68. package/dist/component/sessions.js.map +1 -1
  69. package/dist/component/streamStats.d.ts +4 -4
  70. package/dist/component/streamStats.d.ts.map +1 -1
  71. package/dist/component/streamStats.js +10 -10
  72. package/dist/component/streamStats.js.map +1 -1
  73. package/dist/component/streams.d.ts +3 -3
  74. package/dist/component/streams.js +18 -18
  75. package/dist/component/streams.js.map +1 -1
  76. package/dist/component/sync.d.ts +4 -12
  77. package/dist/component/sync.d.ts.map +1 -1
  78. package/dist/component/sync.js +1 -1
  79. package/dist/component/sync.js.map +1 -1
  80. package/dist/component/syncIngest.d.ts +1 -3
  81. package/dist/component/syncIngest.d.ts.map +1 -1
  82. package/dist/component/syncReplay.d.ts +1 -3
  83. package/dist/component/syncReplay.d.ts.map +1 -1
  84. package/dist/component/syncReplay.js +11 -12
  85. package/dist/component/syncReplay.js.map +1 -1
  86. package/dist/component/threads.d.ts +7 -21
  87. package/dist/component/threads.d.ts.map +1 -1
  88. package/dist/component/threads.js +35 -34
  89. package/dist/component/threads.js.map +1 -1
  90. package/dist/component/turns.d.ts +2 -6
  91. package/dist/component/turns.d.ts.map +1 -1
  92. package/dist/component/turns.js +9 -8
  93. package/dist/component/turns.js.map +1 -1
  94. package/dist/component/turnsInternal.d.ts +1 -1
  95. package/dist/component/turnsInternal.js +3 -3
  96. package/dist/component/turnsInternal.js.map +1 -1
  97. package/dist/component/types.d.ts +4 -10
  98. package/dist/component/types.d.ts.map +1 -1
  99. package/dist/component/types.js +1 -3
  100. package/dist/component/types.js.map +1 -1
  101. package/dist/component/utils.d.ts.map +1 -1
  102. package/dist/component/utils.js +8 -11
  103. package/dist/component/utils.js.map +1 -1
  104. package/dist/host/convex-entry.d.ts +4 -1
  105. package/dist/host/convex-entry.d.ts.map +1 -1
  106. package/dist/host/convex-entry.js +3 -0
  107. package/dist/host/convex-entry.js.map +1 -1
  108. package/dist/host/convexPreset.d.ts +1422 -0
  109. package/dist/host/convexPreset.d.ts.map +1 -0
  110. package/dist/host/convexPreset.js +516 -0
  111. package/dist/host/convexPreset.js.map +1 -0
  112. package/dist/host/convexSlice.d.ts +46 -40
  113. package/dist/host/convexSlice.d.ts.map +1 -1
  114. package/dist/host/convexSlice.js +2 -4
  115. package/dist/host/convexSlice.js.map +1 -1
  116. package/dist/host/index.d.ts +4 -1
  117. package/dist/host/index.d.ts.map +1 -1
  118. package/dist/host/index.js +3 -0
  119. package/dist/host/index.js.map +1 -1
  120. package/dist/host/runtime.d.ts +1 -3
  121. package/dist/host/runtime.d.ts.map +1 -1
  122. package/dist/host/runtime.js +1 -1
  123. package/dist/host/runtime.js.map +1 -1
  124. package/dist/host/surfaceGenerator.d.ts +16 -0
  125. package/dist/host/surfaceGenerator.d.ts.map +1 -0
  126. package/dist/host/surfaceGenerator.js +56 -0
  127. package/dist/host/surfaceGenerator.js.map +1 -0
  128. package/dist/host/surfaceManifest.d.ts +27 -0
  129. package/dist/host/surfaceManifest.d.ts.map +1 -0
  130. package/dist/host/surfaceManifest.js +78 -0
  131. package/dist/host/surfaceManifest.js.map +1 -0
  132. package/dist/host/wrapDefinitions.d.ts +17 -0
  133. package/dist/host/wrapDefinitions.d.ts.map +1 -0
  134. package/dist/host/wrapDefinitions.js +18 -0
  135. package/dist/host/wrapDefinitions.js.map +1 -0
  136. package/docs/CLIENT_AND_REACT_HOOKS.md +99 -0
  137. package/docs/DISPATCH_MANAGED_REFERENCE_HOST.md +64 -0
  138. package/docs/HOST_INTEGRATION.md +89 -0
  139. package/docs/HOST_PRESET_MATRIX.md +72 -0
  140. package/docs/OPERATIONS_AND_ERRORS.md +62 -0
  141. package/docs/RUNTIME_OWNED_REFERENCE_HOST.md +59 -0
  142. package/package.json +8 -3
package/LLMS.md ADDED
@@ -0,0 +1,111 @@
1
+ # LLMS: Canonical Consumer Integration (Single Path)
2
+
3
+ Canonical default: runtime-owned host integration (`dispatchManaged: false`).
4
+
5
+ ## Actor Scope Contract
6
+
7
+ - Actor payload is `actor: { userId?: string }`.
8
+ - `userId` is optional:
9
+ - when present, data access is scoped to that user.
10
+ - when omitted, data access is scoped to anonymous-only rows.
11
+ - Do not send tenant/device identifiers.
12
+
13
+ ## Hard Rule
14
+
15
+ - Follow this file as the only default implementation strategy.
16
+ - Do not implement dispatch-managed orchestration unless explicitly requested.
17
+ - Do not handwrite host wrapper surfaces; generate them.
18
+ - Always use app-generated Convex types from `./_generated/api` and `./_generated/server`.
19
+
20
+ ## Required Implementation Steps
21
+
22
+ 1. Install package dependencies.
23
+
24
+ ```bash
25
+ pnpm add @zakstam/codex-local-component convex
26
+ ```
27
+
28
+ 2. Mount the component in `convex/convex.config.ts`.
29
+
30
+ ```ts
31
+ import { defineApp } from "convex/server";
32
+ import codexLocal from "@zakstam/codex-local-component/convex.config";
33
+
34
+ const app = defineApp();
35
+ app.use(codexLocal);
36
+
37
+ export default app;
38
+ ```
39
+
40
+ 3. Generate host surfaces from the canonical manifest.
41
+
42
+ ```bash
43
+ pnpm run host:generate
44
+ ```
45
+
46
+ 4. Keep host files in this split:
47
+
48
+ - `convex/chat.generated.ts`: generated preset wrappers (do not edit)
49
+ - `convex/chat.extensions.ts`: app-owned custom endpoints
50
+ - `convex/chat.ts`: stable entrypoint (`export *` from generated + extensions)
51
+
52
+ 5. Use runtime-owned host preset behavior only.
53
+
54
+ - Generated wrappers are based on `defineRuntimeOwnedHostSlice(...)`.
55
+ - Runtime startup must be explicit runtime-owned:
56
+
57
+ ```ts
58
+ await runtime.start({
59
+ actor,
60
+ sessionId,
61
+ dispatchManaged: false,
62
+ threadStrategy: "start",
63
+ });
64
+ ```
65
+
66
+ 6. Start turns through `runtime.sendTurn(text)`.
67
+
68
+ - Do not call `startClaimedTurn` in the canonical path.
69
+
70
+ 7. Validate host wiring during startup.
71
+
72
+ - Query `chat.validateHostWiring` once at process boot.
73
+ - Fail fast if `ok` is `false`.
74
+
75
+ 8. Use canonical host query/mutation endpoints in React hooks.
76
+
77
+ - `useCodexMessages` -> `chat.listThreadMessagesForHooks`
78
+ - `useCodexTurn` -> `chat.listTurnMessagesForHooks`
79
+ - `useCodexApprovals` -> `chat.listPendingApprovalsForHooks` + `chat.respondApprovalForHooks`
80
+ - `useCodexComposer` -> `chat.enqueueTurnDispatch`
81
+
82
+ ## Required Consumer Commands
83
+
84
+ From repo root (or equivalent monorepo command wrappers):
85
+
86
+ ```bash
87
+ pnpm run host:generate
88
+ pnpm run host:check
89
+ ```
90
+
91
+ From each host app:
92
+
93
+ ```bash
94
+ pnpm run dev:convex:once
95
+ pnpm run wiring:smoke
96
+ pnpm run typecheck
97
+ ```
98
+
99
+ ## Required Host Surface Ownership
100
+
101
+ - Generated surface owns preset endpoint exports.
102
+ - Extensions file owns only app-specific endpoints.
103
+ - Entrypoint file owns only re-exports.
104
+
105
+ If an endpoint belongs to preset behavior, add it in the package preset/manifest and regenerate. Do not manually patch generated host files.
106
+
107
+ ## Advanced Appendix (Non-Default)
108
+
109
+ Dispatch-managed orchestration is advanced and non-default. Reference only when explicitly requested:
110
+
111
+ - `docs/DISPATCH_MANAGED_REFERENCE_HOST.md`
package/README.md CHANGED
@@ -2,7 +2,9 @@
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/%40zakstam%2Fcodex-local-component)](https://www.npmjs.com/package/@zakstam/codex-local-component)
4
4
 
5
- Convex component for Codex integrations where Codex runs locally on the user's machine (desktop/CLI), while thread state, messages, approvals, and stream recovery live in Convex.
5
+ Convex component for Codex integrations where Codex runs locally while thread state, messages, approvals, and replay are persisted in Convex.
6
+
7
+ Canonical default: runtime-owned host integration (`dispatchManaged: false`).
6
8
 
7
9
  ## Install
8
10
 
@@ -12,214 +14,25 @@ pnpm add @zakstam/codex-local-component convex
12
14
 
13
15
  React hooks require `react` peer dependency (`^18` or `^19`).
14
16
 
15
- ## Integration Contract (Read First)
16
-
17
- 1. Always use generated Convex types from your app:
18
- - `./_generated/api`
19
- - `./_generated/server`
20
- 2. Mount the component once with `app.use(codexLocal)`.
21
- 3. In Convex server files, use `@zakstam/codex-local-component/host/convex` helper exports.
22
- 4. Treat `actor` (`tenantId`, `userId`, `deviceId`) as trusted server identity, not untrusted client input.
23
- 5. Before ingesting events on startup/reconnect, call `sync.ensureSession`.
24
- 6. For runtime ingest, prefer `sync.ingestSafe` (`ingestBatchMixed` uses this).
25
- 7. Runtime dispatch ownership must be explicit:
26
- - `dispatchManaged: false` -> runtime orchestrates via `sendTurn`
27
- - `dispatchManaged: true` -> external worker orchestrates and runtime executes via `startClaimedTurn`
28
- 8. Convex-deployed code should not import `@zakstam/codex-local-component/protocol/parser` (Ajv runtime validation). Use host wrappers and `protocol/events`-based helpers only.
29
-
30
- ## Golden Path
31
-
32
- ### 1) Mount the component
33
-
34
- ```ts
35
- // convex/convex.config.ts
36
- import { defineApp } from "convex/server";
37
- import codexLocal from "@zakstam/codex-local-component/convex.config";
38
-
39
- const app = defineApp();
40
- app.use(codexLocal);
41
-
42
- export default app;
43
- ```
44
-
45
- Run `npx convex dev` once so `components.codexLocal.*` is generated.
46
-
47
- ### 2) Add host wrappers (`convex/chat.ts`)
48
-
49
- ```ts
50
- import { paginationOptsValidator } from "convex/server";
51
- import { v } from "convex/values";
52
- import { mutation, query } from "./_generated/server";
53
- import { components } from "./_generated/api";
54
- import {
55
- enqueueTurnDispatchForActor,
56
- ensureSession as ensureSessionHandler,
57
- ensureThreadByCreate,
58
- ingestBatchMixed,
59
- listThreadMessagesForHooksForActor,
60
- vHostEnqueueTurnDispatchResult,
61
- vHostActorContext,
62
- vHostEnsureSessionResult,
63
- vHostIngestSafeResult,
64
- vHostLifecycleInboundEvent,
65
- vHostStreamArgs,
66
- vHostStreamInboundEvent,
67
- vHostSyncRuntimeOptions,
68
- } from "@zakstam/codex-local-component/host/convex";
69
-
70
- const SERVER_ACTOR = {
71
- tenantId: process.env.ACTOR_TENANT_ID ?? "demo-tenant",
72
- userId: process.env.ACTOR_USER_ID ?? "demo-user",
73
- deviceId: process.env.ACTOR_DEVICE_ID ?? "server-device",
74
- };
75
-
76
- export const ensureThread = mutation({
77
- args: { actor: vHostActorContext, threadId: v.string() },
78
- handler: async (ctx, args) => ensureThreadByCreate(ctx, components.codexLocal, args),
79
- });
80
-
81
- export const enqueueTurnDispatch = mutation({
82
- args: {
83
- actor: vHostActorContext,
84
- threadId: v.string(),
85
- turnId: v.string(),
86
- idempotencyKey: v.string(),
87
- input: v.array(
88
- v.object({
89
- type: v.string(),
90
- text: v.optional(v.string()),
91
- url: v.optional(v.string()),
92
- path: v.optional(v.string()),
93
- }),
94
- ),
95
- },
96
- returns: vHostEnqueueTurnDispatchResult,
97
- handler: async (ctx, args) =>
98
- enqueueTurnDispatchForActor(ctx, components.codexLocal, args),
99
- });
100
-
101
- export const ensureSession = mutation({
102
- args: { actor: vHostActorContext, sessionId: v.string(), threadId: v.string() },
103
- returns: vHostEnsureSessionResult,
104
- handler: async (ctx, args) => ensureSessionHandler(ctx, components.codexLocal, args),
105
- });
106
-
107
- export const ingestBatch = mutation({
108
- args: {
109
- actor: vHostActorContext,
110
- sessionId: v.string(),
111
- threadId: v.string(),
112
- deltas: v.array(v.union(vHostStreamInboundEvent, vHostLifecycleInboundEvent)),
113
- runtime: v.optional(vHostSyncRuntimeOptions),
114
- },
115
- returns: vHostIngestSafeResult,
116
- handler: async (ctx, args) => ingestBatchMixed(ctx, components.codexLocal, args),
117
- });
118
-
119
- export const listThreadMessagesForHooks = query({
120
- args: {
121
- actor: vHostActorContext,
122
- threadId: v.string(),
123
- paginationOpts: paginationOptsValidator,
124
- streamArgs: vHostStreamArgs,
125
- runtime: v.optional(vHostSyncRuntimeOptions),
126
- },
127
- handler: async (ctx, args) =>
128
- listThreadMessagesForHooksForActor(ctx, components.codexLocal, {
129
- actor: SERVER_ACTOR,
130
- threadId: args.threadId,
131
- paginationOpts: args.paginationOpts,
132
- streamArgs: args.streamArgs,
133
- runtime: args.runtime,
134
- }),
135
- });
136
- ```
137
-
138
- ### 3) Run bridge loop (desktop/CLI process)
139
-
140
- ```ts
141
- import { randomUUID } from "node:crypto";
142
- import { ConvexHttpClient } from "convex/browser";
143
- import { CodexLocalBridge } from "@zakstam/codex-local-component/bridge";
144
- import { api } from "../convex/_generated/api.js";
145
-
146
- const convex = new ConvexHttpClient(process.env.CONVEX_URL!);
147
- const actor = { tenantId: "demo", userId: "demo", deviceId: "local-1" };
148
- const sessionId = randomUUID();
149
- let threadId: string | null = null;
150
-
151
- const bridge = new CodexLocalBridge(
152
- { cwd: process.cwd() },
153
- {
154
- onEvent: async (event) => {
155
- if (!threadId) {
156
- threadId = event.threadId;
157
- await convex.mutation(api.chat.ensureThread, { actor, threadId });
158
- await convex.mutation(api.chat.ensureSession, { actor, sessionId, threadId });
159
- }
17
+ ## Canonical Implementation
160
18
 
161
- await convex.mutation(api.chat.ingestBatch, {
162
- actor,
163
- sessionId,
164
- threadId: event.threadId,
165
- deltas: [event],
166
- });
167
- },
168
- onGlobalMessage: async () => {
169
- // handle non-thread protocol messages (auth/config/etc)
170
- },
171
- onProtocolError: async ({ error, line }) => {
172
- console.error("protocol error", error.message, line);
173
- },
174
- },
175
- );
19
+ Use one source of truth for implementation steps:
176
20
 
177
- bridge.start();
178
- ```
179
-
180
- ### 4) Wire React hooks
181
-
182
- ```tsx
183
- import { useCodexMessages } from "@zakstam/codex-local-component/react";
184
- import { api } from "../convex/_generated/api";
185
-
186
- const actor = { tenantId: "demo", userId: "demo", deviceId: "web-1" };
187
-
188
- export function Chat({ threadId }: { threadId: string }) {
189
- const messages = useCodexMessages(
190
- api.chat.listThreadMessagesForHooks,
191
- { actor, threadId },
192
- { initialNumItems: 30, stream: true },
193
- );
194
-
195
- return (
196
- <div>
197
- {messages.results.map((msg) => (
198
- <div key={msg._id}>{msg.text}</div>
199
- ))}
200
- </div>
201
- );
202
- }
203
- ```
204
-
205
- ## Required Query Contract for `useCodexMessages`
206
-
207
- Your host query must:
208
-
209
- - accept `threadId`, `paginationOpts`, optional `streamArgs`
210
- - return durable paginated messages plus optional `streams`
211
-
212
- `streamArgs`:
21
+ - `./LLMS.md`
213
22
 
214
- - `{ kind: "list", startOrder?: number }`
215
- - `{ kind: "deltas", cursors: Array<{ streamId: string; cursor: number }> }`
23
+ That file is the normative, single-path consumer strategy.
216
24
 
217
- Delta stream response shape includes:
25
+ ## Quickstart Summary
218
26
 
219
- - `streams`
220
- - `deltas`
221
- - `streamWindows` (`ok | rebased | stale`)
222
- - `nextCheckpoints`
27
+ 1. Mount component in `convex/convex.config.ts` with `app.use(codexLocal)`.
28
+ 2. Generate host surfaces with `pnpm run host:generate`.
29
+ 3. Keep host split:
30
+ - `convex/chat.generated.ts` (generated)
31
+ - `convex/chat.extensions.ts` (app-owned)
32
+ - `convex/chat.ts` (re-exports)
33
+ 4. Start runtime in runtime-owned mode (`dispatchManaged: false`).
34
+ 5. Call `chat.validateHostWiring` at startup.
35
+ 6. Use `@zakstam/codex-local-component/react` hooks against canonical host endpoints.
223
36
 
224
37
  ## Package Import Paths
225
38
 
@@ -231,54 +44,17 @@ Delta stream response shape includes:
231
44
  - `@zakstam/codex-local-component/app-server`
232
45
  - `@zakstam/codex-local-component/protocol`
233
46
 
234
- ## Dispatch v0.5 Canonical Mode
47
+ ## Docs Map
235
48
 
236
- Use one orchestration owner per runtime instance:
237
-
238
- - Runtime-owned mode: `createCodexHostRuntime(...).start({ dispatchManaged: false, ... })` and call `sendTurn(text)`.
239
- - External dispatch mode: `start({ dispatchManaged: true, ... })`, enqueue/claim via dispatch wrappers, then call `startClaimedTurn({ dispatchId, claimToken, turnId, inputText })`.
240
-
241
- Guardrail: mixing both APIs in one mode throws explicit runtime error codes (`E_RUNTIME_DISPATCH_*`).
242
-
243
- Reference guides:
244
-
245
- - `docs/RUNTIME_OWNED_REFERENCE_HOST.md` for `dispatchManaged: false`.
246
- - `docs/DISPATCH_MANAGED_REFERENCE_HOST.md` for `dispatchManaged: true`.
247
-
248
- ## Implemented
249
-
250
- - Initialization handshake
251
- - Thread lifecycle (create, resolve, resume, fork, archive, rollback)
252
- - Turn lifecycle (start, interrupt, idempotency)
253
- - Streamed event ingest and replay with cursor-based sync
254
- - Session lifecycle (`ensureSession`, heartbeat, recovery)
255
- - Account/Auth API surface (`account/read`, `account/login/start`, `account/login/cancel`, `account/logout`, `account/rateLimits/read`)
256
- - Command execution and file change approval flows
257
- - Tool user input flow
258
- - Dynamic tool call response flow
259
- - ChatGPT auth-token refresh response flow (`account/chatgptAuthTokens/refresh`)
260
- - Multi-device stream checkpoints with TTL cleanup
261
-
262
- ## Not Implemented Yet
263
-
264
- - Config management API surface
265
- - MCP management API surface
266
- - Core runtime utility APIs (`command/exec`, `model/list`, `review/start`)
267
- - Skill/App discovery and configuration APIs
268
- - Feedback API
269
- - Collaboration mode listing
270
-
271
- ## Docs
272
-
273
- - `docs/HOST_INTEGRATION.md`
274
- - `docs/RUNTIME_OWNED_REFERENCE_HOST.md`
275
- - `docs/DISPATCH_MANAGED_REFERENCE_HOST.md`
276
- - `docs/CLIENT_AND_REACT_HOOKS.md`
277
- - `docs/OPERATIONS_AND_ERRORS.md`
49
+ - Canonical implementation: `./LLMS.md`
50
+ - Host details (aligned to canonical path): `docs/HOST_INTEGRATION.md`
51
+ - Client and hooks contracts: `docs/CLIENT_AND_REACT_HOOKS.md`
52
+ - Operations and errors: `docs/OPERATIONS_AND_ERRORS.md`
53
+ - Reference matrix: `docs/HOST_PRESET_MATRIX.md`
54
+ - Advanced appendix (non-default): `docs/DISPATCH_MANAGED_REFERENCE_HOST.md`
55
+ - Runtime-owned reference details: `docs/RUNTIME_OWNED_REFERENCE_HOST.md`
278
56
 
279
57
  ## Type Safety Checks
280
58
 
281
59
  - `pnpm --filter @zakstam/codex-local-component run typecheck`
282
60
  - `pnpm --filter @zakstam/codex-local-component run check:unsafe-types`
283
-
284
- `check:unsafe-types` fails on handwritten-source `any` usage and on new casts outside `scripts/unsafe-cast-allowlist.txt` (generated files excluded).
@@ -9,9 +9,30 @@
9
9
  import type * as approvals from "../approvals.js";
10
10
  import type * as dispatch from "../dispatch.js";
11
11
  import type * as index from "../index.js";
12
+ import type * as ingest_applyApprovals from "../ingest/applyApprovals.js";
13
+ import type * as ingest_applyMessages from "../ingest/applyMessages.js";
14
+ import type * as ingest_applyStreams from "../ingest/applyStreams.js";
15
+ import type * as ingest_applyTurns from "../ingest/applyTurns.js";
16
+ import type * as ingest_checkpoints from "../ingest/checkpoints.js";
17
+ import type * as ingest_index from "../ingest/index.js";
18
+ import type * as ingest_normalize from "../ingest/normalize.js";
19
+ import type * as ingest_postIngest from "../ingest/postIngest.js";
20
+ import type * as ingest_sessionGuard from "../ingest/sessionGuard.js";
21
+ import type * as ingest_stateCache from "../ingest/stateCache.js";
22
+ import type * as ingest_types from "../ingest/types.js";
23
+ import type * as messages from "../messages.js";
24
+ import type * as pagination from "../pagination.js";
25
+ import type * as reasoning from "../reasoning.js";
26
+ import type * as scope from "../scope.js";
27
+ import type * as serverRequests from "../serverRequests.js";
12
28
  import type * as sessions from "../sessions.js";
29
+ import type * as streamStats from "../streamStats.js";
13
30
  import type * as streams from "../streams.js";
14
31
  import type * as sync from "../sync.js";
32
+ import type * as syncHelpers from "../syncHelpers.js";
33
+ import type * as syncIngest from "../syncIngest.js";
34
+ import type * as syncReplay from "../syncReplay.js";
35
+ import type * as syncRuntime from "../syncRuntime.js";
15
36
  import type * as threads from "../threads.js";
16
37
  import type * as turns from "../turns.js";
17
38
  import type * as turnsInternal from "../turnsInternal.js";
@@ -22,9 +43,30 @@ declare const fullApi: ApiFromModules<{
22
43
  approvals: typeof approvals;
23
44
  dispatch: typeof dispatch;
24
45
  index: typeof index;
46
+ "ingest/applyApprovals": typeof ingest_applyApprovals;
47
+ "ingest/applyMessages": typeof ingest_applyMessages;
48
+ "ingest/applyStreams": typeof ingest_applyStreams;
49
+ "ingest/applyTurns": typeof ingest_applyTurns;
50
+ "ingest/checkpoints": typeof ingest_checkpoints;
51
+ "ingest/index": typeof ingest_index;
52
+ "ingest/normalize": typeof ingest_normalize;
53
+ "ingest/postIngest": typeof ingest_postIngest;
54
+ "ingest/sessionGuard": typeof ingest_sessionGuard;
55
+ "ingest/stateCache": typeof ingest_stateCache;
56
+ "ingest/types": typeof ingest_types;
57
+ messages: typeof messages;
58
+ pagination: typeof pagination;
59
+ reasoning: typeof reasoning;
60
+ scope: typeof scope;
61
+ serverRequests: typeof serverRequests;
25
62
  sessions: typeof sessions;
63
+ streamStats: typeof streamStats;
26
64
  streams: typeof streams;
27
65
  sync: typeof sync;
66
+ syncHelpers: typeof syncHelpers;
67
+ syncIngest: typeof syncIngest;
68
+ syncReplay: typeof syncReplay;
69
+ syncRuntime: typeof syncRuntime;
28
70
  threads: typeof threads;
29
71
  turns: typeof turns;
30
72
  turnsInternal: typeof turnsInternal;
@@ -1 +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"}
1
+ {"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/component/_generated/api.ts"],"names":[],"mappings":"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"}
@@ -1 +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"}
1
+ {"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"}