agent-director 0.16.0 → 0.17.0
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.
- package/README.md +3 -3
- package/dist/errors.d.ts +3 -2
- package/dist/types.d.ts +22 -19
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -427,10 +427,10 @@ tool ran or Cursor supplied validated exact matching invocation proof under
|
|
|
427
427
|
MCP invocation that proves dialog closure without inferring execution or changing
|
|
428
428
|
decision, delivery or pane-answer fields;
|
|
429
429
|
`"turn_end"`, an eligible main request's turn ended under the age and identity
|
|
430
|
-
guards; or `"agent_gone"`,
|
|
430
|
+
guards; or `"agent_gone"`, a non-Cursor agent ended) say when and how the request's
|
|
431
431
|
dialog was proven gone; `"delivered"` and a pane answer are
|
|
432
432
|
agent-director's own records, not proof. `get`'s `unproven_requests` lists
|
|
433
|
-
every request
|
|
433
|
+
every request still holding the dialog, each with `unproven_since`. A request
|
|
434
434
|
that reads `"delivered"` or closed at the pane can remain unproven; its dialog
|
|
435
435
|
may still be there. Handling is in the
|
|
436
436
|
[caller contract](../../docs/caller-contract.md#permission-relay).
|
|
@@ -692,7 +692,7 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
|
|
|
692
692
|
|---|---|
|
|
693
693
|
| `ErrSendKeysWhileRelayed` | A `sendKeys` or `pause` while the request relay may still answer. Nothing was sent. The message distinguishes an undecided request from a recorded verdict still being delivered; see the [caller contract](../../docs/caller-contract.md#permission-relay). |
|
|
694
694
|
| `ErrRelayFallenBack` | The request's relay settled without acknowledgement and no pane answer is recorded through agent-director. Cursor uses finite `confirm_by` with null per-request hook process evidence; see [Cursor permissions](../../docs/permissions.md#cursor-spawns). Thrown by `decide` on that request, within seconds of the hook's end (after the request's `confirm_by` when agent-director cannot check the hook's process); no verdict was recorded, the caller's is kept as the request's `attempted_decision`. Thrown by a `sendKeys` without `request_token`, and by `pause`, while any request of the spawn is so; nothing was sent. `errDetails` is a `RelayFallenBackDetails`: the request's facts, the spawn's `state` and its other `open_requests`. Pane-answer handling is owned by [Permission relay](../../docs/caller-contract.md#permission-relay); the relevant API methods are `sendKeys` with `request_token` and `recordPaneAnswer`. For a request recorded by an older binary, `decide` throws it once the request's record is still open 2 s after its relay window ended (a call from 1 s before the window ends first waits for that instant, at most 3 s), and only while the spawn is still in `check_permission` with no other open request and none recorded after this one, otherwise `ErrNoOpenPermissionRequest`. |
|
|
695
|
-
| `ErrDialogMaybeOpen` | A `sendKeys` without `request_token` and without `expect_pane_sha256`, or a `pause`, on a spawn with `relay_mode=on`, while a permission request of the spawn is not proven gone by valid agent evidence (see [The dialog hold](../../docs/permissions.md#the-dialog-hold)), whatever agent-director's records say of it (`"delivered"`, a pane answer, `recordPaneAnswer`); nothing was sent. `errDetails` is a `DialogMaybeOpenDetails`: the oldest such request with its facts and `unproven_since`, the spawn's `state` and its other `unproven_requests`. Retry, escalation and pane-hash handling are owned by [Permission relay](../../docs/caller-contract.md#permission-relay). `pause` takes no hash; stopping a held Spawn is covered by [Caller contract](../../docs/caller-contract.md). |
|
|
695
|
+
| `ErrDialogMaybeOpen` | A `sendKeys` without `request_token` and without `expect_pane_sha256`, or a `pause`, on a spawn with `relay_mode=on`, while a permission request of the spawn is not proven gone by valid agent evidence and is not a Cursor request of an earlier launch (see [The dialog hold](../../docs/permissions.md#the-dialog-hold)), whatever agent-director's records say of it (`"delivered"`, a pane answer, `recordPaneAnswer`); nothing was sent. `errDetails` is a `DialogMaybeOpenDetails`: the oldest such request with its facts and `unproven_since`, the spawn's `state` and its other `unproven_requests`. Retry, escalation and pane-hash handling are owned by [Permission relay](../../docs/caller-contract.md#permission-relay). `pause` takes no hash; stopping a held Spawn is covered by [Caller contract](../../docs/caller-contract.md). |
|
|
696
696
|
| `ErrPaneChanged` | `sendKeys` or `recordPaneAnswer` with `expect_pane_sha256`: the agent's pane no longer has that hash; nothing was sent or recorded. `errDetails` (`PaneChangedDetails`) never carries the new hash; shared pane handling is in [Permission relay](../../docs/caller-contract.md#permission-relay). |
|
|
697
697
|
| `ErrPaneAnswerInProgress` | A pane answer or `recordPaneAnswer` while another sender still owns the request. Nothing was sent or recorded; `errDetails` is `PaneAnswerInProgressDetails`. |
|
|
698
698
|
| `ErrClaimTooSoon` | `recordPaneAnswer` before the request's relay hook has been gone 2 s, or while it may still answer the request; nothing was recorded. `errDetails` is `ClaimTooSoonDetails`, with `not_before` (`null` only while the hook is seen running); retry handling is in [Permission relay](../../docs/caller-contract.md#permission-relay). |
|
package/dist/errors.d.ts
CHANGED
|
@@ -364,8 +364,9 @@ export declare class ErrClaimTooSoon extends AgentDirectorError {
|
|
|
364
364
|
/**
|
|
365
365
|
* Mirrors ErrDialogMaybeOpen (package: api): a plain `sendKeys` without `expect_pane_sha256`, or
|
|
366
366
|
* a `pause`, while a permission request of the Spawn is not proven gone by the agent's hooks
|
|
367
|
-
* (its tool's PostToolUse, the main agent's end of turn after it, or
|
|
368
|
-
* agent-director's records say of it; its dialog may still be on the pane.
|
|
367
|
+
* (its tool's PostToolUse, the main agent's end of turn after it, or, on a non-Cursor Spawn, the
|
|
368
|
+
* agent's end), whatever agent-director's records say of it; its dialog may still be on the pane.
|
|
369
|
+
* A Cursor request of an earlier launch of the Spawn does not count. Nothing was sent.
|
|
369
370
|
* `errDetails` is a `DialogMaybeOpenDetails`. A plain `sendKeys` whose `expect_pane_sha256`
|
|
370
371
|
* matches the pane is not rejected with it; pass that hash only from a pane a person or LLM
|
|
371
372
|
* judged, never from an automatic flow.
|
package/dist/types.d.ts
CHANGED
|
@@ -182,7 +182,8 @@ export interface RequestDelivery {
|
|
|
182
182
|
* When agent evidence proved the request's permission dialog gone; null until
|
|
183
183
|
* then. agent-director's own records (`delivered`, a pane answer, `recordPaneAnswer`) are not
|
|
184
184
|
* proof. While it is null, a plain `sendKeys` to the live Spawn without `expect_pane_sha256`,
|
|
185
|
-
* and a `pause`, reject with `ErrDialogMaybeOpen
|
|
185
|
+
* and a `pause`, reject with `ErrDialogMaybeOpen`, unless it is a Cursor request of an earlier
|
|
186
|
+
* launch of the row.
|
|
186
187
|
*/
|
|
187
188
|
proven_gone_at: string | null;
|
|
188
189
|
/** How it was proven gone; see {@link ProvenGoneHow}. Null until proven. */
|
|
@@ -205,15 +206,15 @@ export interface RequestDelivery {
|
|
|
205
206
|
* before the hook began. Legacy non-Cursor main requests retain eligibility; Cursor
|
|
206
207
|
* unknown-origin and child requests remain ineligible even without a child id. Decisions,
|
|
207
208
|
* delivery acknowledgements and pane-answer claims do not grant eligibility.
|
|
208
|
-
* - `"agent_gone"`: its Spawn was marked missing, ended or resumed.
|
|
209
|
+
* - `"agent_gone"`: its non-Cursor Spawn was marked missing, ended or resumed.
|
|
209
210
|
*/
|
|
210
211
|
export type ProvenGoneHow = "tool_ran" | "turn_end" | "agent_gone";
|
|
211
212
|
/**
|
|
212
213
|
* One permission request with its delivery facts:
|
|
213
214
|
* an open one (still awaiting an answer) in the `permission_requests` of a `get` or `list` row in
|
|
214
|
-
* state check_permission; one not proven gone,
|
|
215
|
-
*
|
|
216
|
-
* `RelayFallenBackDetails` and `DialogMaybeOpenDetails`).
|
|
215
|
+
* state check_permission; one that holds the dialog (not proven gone, less a Cursor request of an
|
|
216
|
+
* earlier launch), open or read closed, in `get`'s `unproven_requests`; and the request an
|
|
217
|
+
* `errDetails` names (the base of `RelayFallenBackDetails` and `DialogMaybeOpenDetails`).
|
|
217
218
|
*/
|
|
218
219
|
export interface PermissionRequestInfo extends RequestDelivery {
|
|
219
220
|
/** Autoincrement primary key of the permission_requests row. */
|
|
@@ -689,15 +690,16 @@ export interface GetResult {
|
|
|
689
690
|
*/
|
|
690
691
|
permission_requests: PermissionRequestInfo[];
|
|
691
692
|
/**
|
|
692
|
-
* Every permission request of the row that the agent's hooks have not proven gone
|
|
693
|
-
* null),
|
|
694
|
-
*
|
|
695
|
-
* (delivered, answered at the pane,
|
|
696
|
-
* `unproven_since`. While it is not empty, a plain
|
|
697
|
-
* and a `pause`, reject (`ErrDialogMaybeOpen`, or an
|
|
698
|
-
* row's live state and is never delayed by
|
|
699
|
-
* with `state` for up to settle_ms under
|
|
700
|
-
*
|
|
693
|
+
* Every permission request of the row that the agent's hooks have not proven gone
|
|
694
|
+
* (`proven_gone_at` null), less Cursor requests of an earlier launch of the row, oldest first,
|
|
695
|
+
* in any live state but ended and missing (`[]` on those). Unlike `permission_requests` it
|
|
696
|
+
* also lists requests agent-director's records read closed (delivered, answered at the pane,
|
|
697
|
+
* or recorded answered outside it), each with `unproven_since`. While it is not empty, a plain
|
|
698
|
+
* `sendKeys` without `expect_pane_sha256`, and a `pause`, reject (`ErrDialogMaybeOpen`, or an
|
|
699
|
+
* earlier relay refusal). It follows the row's live state and is never delayed by
|
|
700
|
+
* `[state] settle_ms`, so with it set it can disagree with `state` for up to settle_ms under
|
|
701
|
+
* ordinary raw-state settling, and without that bound while entering or leaving
|
|
702
|
+
* `needs_intelligence` or `idle_screen` (see `state`).
|
|
701
703
|
*/
|
|
702
704
|
unproven_requests: PermissionRequestInfo[];
|
|
703
705
|
}
|
|
@@ -931,11 +933,12 @@ export interface RelayFallenBackDetails extends PermissionRequestInfo {
|
|
|
931
933
|
open_requests: OpenRequestFacts[] | null;
|
|
932
934
|
}
|
|
933
935
|
/**
|
|
934
|
-
* ErrDialogMaybeOpen's errDetails (from a plain
|
|
935
|
-
*
|
|
936
|
-
*
|
|
937
|
-
* say it closed, `delivery` and `pane_answer`, and since when,
|
|
938
|
-
* state, and the Spawn's other requests
|
|
936
|
+
* ErrDialogMaybeOpen's errDetails (from a plain sendKeys without `expect_pane_sha256`, and
|
|
937
|
+
* from pause): the oldest request of the Spawn that holds the dialog (not proven gone, less a
|
|
938
|
+
* Cursor request of an earlier launch), with its fields and delivery facts (how
|
|
939
|
+
* agent-director's records say it closed, `delivery` and `pane_answer`, and since when,
|
|
940
|
+
* `unproven_since`), the Spawn's state, and the Spawn's other such requests (as
|
|
941
|
+
* `unproven_requests` lists them), oldest first.
|
|
939
942
|
*/
|
|
940
943
|
export interface DialogMaybeOpenDetails extends PermissionRequestInfo {
|
|
941
944
|
state: string;
|