jg-agent-hq 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.5.0
+
+- Add safe publication observations for the host's System view, with separate pending, blocked, failed and uncertain states, timestamps and exact commit identity.
+- Bind publication retries to a receipt UUID and nullable expected commit, including failures that happened before a commit existed. The host continues to own scheduling, Git operations and storage.
+
+## 0.4.0
+
+- Add closed browser host commands and bounded session/repository/plan read contracts, without exposing private handlers through standalone IPC.
+- Persist operator-bound host action receipts before effects, reject changed replays, retain uncertainty across restart and join exact server-owned native child receipts.
+- Add conditional live-window reads so unchanged SSE polling does not repeatedly copy or serialize conversation bodies.
+
 ## 0.3.0
 
 - Publish the consumer-tested package through the configured GitHub Actions trusted publisher before deploying the website. Verify release ordering and archive integrity, and safely skip identical published versions.

package/README.md

@@ -45,7 +45,9 @@ Use `--provider claude` for Claude history and usage; the default is `codex`. Cl
 
 Explicit actions create, name, adopt, resume and close threads; send idle messages; steer an exact running turn; queue the next message; interrupt; and answer native questions or permissions. Actions have stable UUIDs and durable receipts. Repeating the same request returns its receipt; changing that UUID's payload conflicts. A lost acknowledgement stays uncertain until the exact native response arrives or the operator makes an explicit recovery choice. HQ never resends uncertain input.
 
-Native execution settings, instructions, skills and tool permissions remain with each CLI. Claude uses an owned structured process per controlled session and reports immediate steering as unavailable. Plan approval grants no native tool permission. Close other CLI controllers before confirming adoption, resume or recovery. HQ coordinates sessions sharing one state directory; it cannot lock independently running native CLIs. Durable state includes `action.key`, which must stay private and accompany its SQLite database. Queued undelivered text is saved; ordinary message bodies and question answers are not.
+Native execution settings, instructions, skills and tool permissions remain with each CLI. Claude uses an owned structured process per controlled session and reports immediate steering as unavailable. Plan approval grants no native tool permission. Close other CLI controllers before confirming adoption, resume or recovery. HQ coordinates sessions sharing one state directory; it cannot lock independently running native CLIs. Integrating browser hosts can use durable host-action admission and operator-scoped reconciliation through the programmatic API; see the [browser host contract](api/README.md#browser-host-integration). The standalone CLI advertises only commands it implements.
+
+Durable state includes `action.key`, which must stay private and accompany its SQLite database. Queued undelivered text is saved; ordinary message bodies and question answers are not.
 
 Use `suggest-thread-name --topic "Build usage" --state-root <directory>` for an editable label and `managed-thread-name --name build-usage --state-root <directory>` to resolve it. Creation adds a short ordinal suffix when a name is occupied. Actions and relationships retain immutable IDs.
 

package/api/README.md

@@ -124,17 +124,17 @@ Trusted runtime construction also accepts `codexExtraSkillRoots?: string[]` and
 
 ## Control reads and reconnect
 
-| Command               | Fields                                            | Result                                                                                                |
-| --------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `managed-threads`     | `workspaceRoot`, optional `limit`, `cursor`       | Creation/UUID seek page of HQ records, including inactive and uncertain states.                       |
-| `managed-thread`      | `threadId`                                        | One HQ record or null.                                                                                |
-| `managed-thread-name` | `name`                                            | One HQ record or null, with case-insensitive lookup and the same workspace authorization.             |
-| `suggest-thread-name` | `topic`                                           | An editable lowercase label, with a currently free suffix when needed. This read does not reserve it. |
-| `receipt`             | `actionId`                                        | One receipt or null.                                                                                  |
-| `actions`             | `threadId`, optional `limit`, `cursor`            | Creation/UUID seek page of action metadata without queued bodies.                                     |
-| `events`              | `threadId`, optional `after` (default 0), `limit` | Ascending durable sequence page and `hasMore`; continue after the final sequence.                     |
-| `approvals`           | `threadId`                                        | Current in-memory native prompts, including exact scope and question metadata.                        |
-| `live-items`          | `threadId`                                        | Active/awaiting-flush item window and `hasGap`.                                                       |
+| Command               | Fields                                            | Result                                                                                                                                  |
+| --------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `managed-threads`     | `workspaceRoot`, optional `limit`, `cursor`       | Creation/UUID seek page of HQ records, including inactive and uncertain states.                                                         |
+| `managed-thread`      | `threadId`                                        | One HQ record or null.                                                                                                                  |
+| `managed-thread-name` | `name`                                            | One HQ record or null, with case-insensitive lookup and the same workspace authorization.                                               |
+| `suggest-thread-name` | `topic`                                           | An editable lowercase label, with a currently free suffix when needed. This read does not reserve it.                                   |
+| `receipt`             | `actionId`                                        | One receipt or null.                                                                                                                    |
+| `actions`             | `threadId`, optional `limit`, `cursor`            | Creation/UUID seek page of action metadata without queued bodies.                                                                       |
+| `events`              | `threadId`, optional `after` (default 0), `limit` | Ascending durable sequence page and `hasMore`; continue after the final sequence.                                                       |
+| `approvals`           | `threadId`                                        | Current in-memory native prompts, including exact scope and question metadata.                                                          |
+| `live-items`          | `threadId`                                        | Active/awaiting-flush item window, `hasGap`, `revision` and `unchanged`. Optional `afterRevision` omits bodies for an unchanged window. |
 
 The installed CLI exposes `managed-thread-name --name <name>` and `suggest-thread-name --topic <topic>`. Suggestions normalize punctuation to hyphens, keep at most 32 characters, and use `session` when the topic contains no ASCII letters or digits. Creation checks availability again inside its admission transaction. All action targets, histories and relationships continue to use immutable HQ/native identities. Name lookup never adopts, resumes or starts a native session.
 
@@ -255,3 +255,19 @@ Feedback resolves installed `jg-feedback` in the author thread and carries the s
 Delivery is `prepared`, `queued`, `submitted`, `delivered`, `uncertain`, `failed` or `canceled`; native `completion` is separately null, `completed`, `failed` or `interrupted`. Acknowledgement alone becomes `delivered`. Busy destinations use native next-turn queues, including while waiting for permissions; feedback is never written as a permission answer. Pending native permissions remain explicit actions on their own channels. No automatic feedback, response loop, approval or publication follows collection.
 
 Lists use indexed `createdAt DESC, id DESC` seek ordering, default 32/max 128, and cursors bound to the workspace, source filter and page size. Concurrent newer inserts do not reappear on continuation; deleted unseen records disappear. Summaries do not transfer retained finding bodies through the worker. SQLite owns the small private `handoff` and `handoff_dispatch` records alongside existing actions. No database migration or transcript mirror is required. Reads are fresh and bounded; no separate cache is used.
+
+## Browser host integration
+
+`jg-agent-hq/contracts` exports closed `BrowserActionSchema`, `BrowserCommandSchema` and `BrowserReceiptSchema` contracts, plus browser session, repository and bounded plan read models. These schemas contain generic identities, not a deployment registry or private handler implementation. They do not expose native RPC, executables or provider configuration. Standalone IPC continues to support only its existing owned commands.
+
+A trusted Node host calls `runtime.performBrowserAction(request, operatorId, execute)` after validating its signed operator identity. The host supplies one dispatcher function in process. It must validate every target against its registry, check operation-specific revisions/turns, and normalize approval provenance to that authenticated operator. Never accept a callback, operator identity or handler name from HTTP input. The request has a stable UUID, current runtime epoch and one closed command: native, plan, handoff, priority, error-reservation or publication-retry. The complete serialized request is limited to 2 MiB; nested native commands retain their tighter limits.
+
+SQLite records an HMAC digest and receipt before invoking the dispatcher. The same UUID and identical normalized request returns the stored receipt without invoking it again. Changed payloads or operators conflict. New requests require the current epoch. Replaying a saved request after restart reconciles it without granting execution authority. Submitted receipts from another runtime become uncertain. Dispatcher failure also leaves the receipt uncertain because its effects may already have committed. This state never automatically resends an effect.
+
+The dispatcher receives a server-owned `nativeActionId`; use this ID for a native child action, preserving the validated runtime and command. `readBrowserAction(id, operatorId)` returns only that operator's receipt and joins its exact native receipt. Host acknowledgement means the handler completed, not that a native turn completed. An unknown or differently owned ID returns null. Receipts retain metadata rather than message bodies or arbitrary handler output. Subsequent domain reads provide the result. At most 32 host jobs are admitted concurrently. Runtime close rejects new host work and waits for admitted work before closing its worker.
+
+`PublicationStatusSchema` is a browser-safe observation supplied by the host, independent of native execution and quota states. It contains the receipt UUID, state/reason, due/attempt/success timestamps, nullable pending and published commit hashes, and bounded queued/selected file counts. It contains no artifact bodies, paths, credentials or deployment configuration. `publication-retry` requires `publicationId` and `expectedCommit` (null before a commit exists). The host must compare both against its current receipt before acting and reconcile or retry only its recorded verified commit. The public runtime supplies no Git publisher, service installer or publication storage.
+
+Live reads accept `afterRevision`. A matching revision returns `unchanged: true` with an empty data array; retain the displayed window. A changed revision returns the complete bounded window. Revisions belong to one runtime. After reconnect to a new runtime, discard the revision and refresh native history. Token bodies stay in the existing bounded memory window and are never copied into lifecycle or browser-action tables.
+
+`thread-plan` accepts a managed `threadId` and returns its nullable `ActionPlanContextSchema`. The host verifies the thread's registered checkout before exposing it. It is read-only and grants no execution authority.

package/dist/actions/live/live.d.ts

@@ -3,6 +3,7 @@ import type { IHistoryItem } from '../../contracts/index.js';
 export declare class LiveItems {
     private readonly __threads;
     private __bytes;
+    private __revision;
     /** Starts a known presentation window without discarding retained awaiting-flush items. */
     open(nativeId: string): void;
     /** Replaces one native item without persisting token or tool-output bodies. */
@@ -14,7 +15,9 @@ export declare class LiveItems {
     /** Appends bounded text; a truncated prefix is never presented as the complete item. */
     append(nativeId: string, turnId: string, itemId: string, delta: string): void;
     /** Returns a copy of the bounded window and explicit incompleteness evidence. */
-    read(nativeId: string): {
+    read(nativeId: string, afterRevision?: number): {
+        revision: number;
+        unchanged: boolean;
         data: (IHistoryItem & {
             state: 'active' | 'awaiting-flush';
         })[];

package/dist/actions/live/live.js

@@ -4,13 +4,14 @@ const MAX_LIVE_BYTES = 4 * 1024 * 1024;
 export class LiveItems {
     __threads = new Map();
     __bytes = 0;
+    __revision = 0;
     /** Starts a known presentation window without discarding retained awaiting-flush items. */
     open(nativeId) {
         if (this.__threads.has(nativeId))
             return;
         if (this.__threads.size >= 32)
             this.__remove(this.__threads.keys().next().value);
-        this.__threads.set(nativeId, { items: new Map(), hasGap: false });
+        this.__threads.set(nativeId, { items: new Map(), hasGap: false, revision: ++this.__revision });
     }
     /** Replaces one native item without persisting token or tool-output bodies. */
     put(nativeId, item, isComplete) {
@@ -18,9 +19,10 @@ export class LiveItems {
         if (!thread) {
             if (this.__threads.size >= 32)
                 this.__remove(this.__threads.keys().next().value);
-            thread = { items: new Map(), hasGap: true };
+            thread = { items: new Map(), hasGap: true, revision: ++this.__revision };
             this.__threads.set(nativeId, thread);
         }
+        thread.revision = ++this.__revision;
         const key = JSON.stringify([item.turnId, item.nativeId]);
         const previous = thread.items.get(key);
         if (previous)
@@ -40,8 +42,10 @@ export class LiveItems {
     /** Marks missing native stream evidence without discarding the surviving presentation. */
     markGap(nativeId) {
         const thread = this.__threads.get(nativeId);
-        if (thread)
+        if (thread) {
             thread.hasGap = true;
+            thread.revision = ++this.__revision;
+        }
     }
     /** Replaces an ephemeral stream identity when the native persisted identity arrives. */
     replace(nativeId, turnId, itemId) {
@@ -52,14 +56,17 @@ export class LiveItems {
             return;
         this.__bytes -= entry.bytes;
         thread.items.delete(key);
+        thread.revision = ++this.__revision;
     }
     /** Appends bounded text; a truncated prefix is never presented as the complete item. */
     append(nativeId, turnId, itemId, delta) {
         const thread = this.__threads.get(nativeId);
         const entry = thread?.items.get(JSON.stringify([turnId, itemId]));
         if (!entry || entry.isComplete) {
-            if (thread)
+            if (thread) {
                 thread.hasGap = true;
+                thread.revision = ++this.__revision;
+            }
             return;
         }
         if (entry.item.isTruncated)
@@ -75,10 +82,13 @@ export class LiveItems {
         }, false);
     }
     /** Returns a copy of the bounded window and explicit incompleteness evidence. */
-    read(nativeId) {
+    read(nativeId, afterRevision) {
         const thread = this.__threads.get(nativeId);
+        const revision = thread?.revision ?? this.__revision;
         return {
-            data: thread
+            revision,
+            unchanged: afterRevision === revision,
+            data: thread && afterRevision !== revision
                 ? [...thread.items.values()].map((entry) => ({
                     ...entry.item,
                     state: entry.isComplete ? 'awaiting-flush' : 'active',
@@ -98,12 +108,15 @@ export class LiveItems {
             if (entry?.isComplete && JSON.stringify(entry.item) === JSON.stringify(item)) {
                 this.__bytes -= entry.bytes;
                 thread.items.delete(key);
+                thread.revision = ++this.__revision;
             }
         }
     }
     /** Keeps interrupted partial items available while their final native history is pending. */
     completeTurn(nativeId, turnId) {
         const thread = this.__threads.get(nativeId);
+        if (thread)
+            thread.revision = ++this.__revision;
         if (thread)
             for (const entry of thread.items.values())
                 if (entry.item.turnId === turnId)
@@ -116,10 +129,12 @@ export class LiveItems {
             for (const entry of thread.items.values())
                 this.__bytes -= entry.bytes;
         this.__threads.delete(nativeId);
+        this.__revision += 1;
     }
     /** Releases every retained body when the owning runtime has stopped. */
     clear() {
         this.__threads.clear();
+        this.__revision += 1;
         this.__bytes = 0;
     }
     __drop(thread, key) {
@@ -128,6 +143,7 @@ export class LiveItems {
             return;
         this.__bytes -= entry.bytes;
         thread.items.delete(key);
+        thread.revision = ++this.__revision;
         thread.hasGap = true;
     }
 }

package/dist/actions/reads.d.ts

@@ -2,7 +2,7 @@ import type { IHqRequest, IHqResponse } from '../contracts/index.js';
 import type { IStore } from '../store/index.js';
 import type { createActions } from './actions.js';
 type IControlRead = Extract<IHqRequest, {
-    kind: 'receipt' | 'managed-threads' | 'managed-thread' | 'managed-thread-name' | 'actions' | 'events' | 'approvals' | 'live-items';
+    kind: 'thread-plan' | 'receipt' | 'managed-threads' | 'managed-thread' | 'managed-thread-name' | 'actions' | 'events' | 'approvals' | 'live-items';
 }>;
 /**
  * Authorizes bounded control reads and binds seek positions to their exact query.

package/dist/actions/reads.js

@@ -75,6 +75,8 @@ export const readControl = async (command, store, actions, roots) => {
     }
     const thread = await store.getThread(command.threadId);
     await authorize(thread);
+    if (command.kind === 'thread-plan')
+        return { kind: 'thread-plan', result: thread ? await store.getThreadPlan(thread.id) : null };
     if (command.kind === 'managed-thread')
         return { kind: command.kind, result: thread };
     if (!thread)
@@ -95,7 +97,7 @@ export const readControl = async (command, store, actions, roots) => {
     return {
         kind: 'live-items',
         result: thread.nativeId
-            ? actions.live.read(JSON.stringify([thread.provider, thread.nativeId]))
-            : { data: [], hasGap: false },
+            ? actions.live.read(JSON.stringify([thread.provider, thread.nativeId]), command.afterRevision)
+            : { data: [], hasGap: false, revision: 0, unchanged: command.afterRevision === 0 },
     };
 };

package/dist/contracts/browser/index.d.ts

@@ -0,0 +1,5 @@
+export { BrowserCommandSchema, BrowserActionSchema, BrowserReceiptSchema } from './types.js';
+export type { IBrowserAction, IBrowserReceipt } from './types.js';
+export { BrowserRepositorySchema, BrowserPlanSummarySchema, BrowserPlanPageSchema, BrowserPlanDetailSchema, BrowserSessionSchema, } from './types.js';
+export { BrowserRepositoryPageSchema, BrowserSystemSchema, BrowserThreadDetailSchema, PublicationStatusSchema, } from './types.js';
+export type { IPublicationStatus } from './types.js';

package/dist/contracts/browser/index.js

@@ -0,0 +1,6 @@
+// browser requests and durable reconciliation
+export { BrowserCommandSchema, BrowserActionSchema, BrowserReceiptSchema } from './types.js';
+// host read models
+export { BrowserRepositorySchema, BrowserPlanSummarySchema, BrowserPlanPageSchema, BrowserPlanDetailSchema, BrowserSessionSchema, } from './types.js';
+// bounded host views
+export { BrowserRepositoryPageSchema, BrowserSystemSchema, BrowserThreadDetailSchema, PublicationStatusSchema, } from './types.js';