@superdurable/dex-agents 0.5.0 → 0.6.0

package/README.md

@@ -487,7 +487,8 @@ if (snapshot.plan?.status === "draft") {
   never runs. It marks the plan `active`, writes `plan_execution_started`, and
   starts an `executing` turn with every tool, whose user message is `[Dex] The
   user approved plan revision <n>. Execute it and keep the task statuses
-  current with write_todos.`.
+  current with write_todos.`. The stored message has `origin`
+  `plan_execution`; see [User messages the session writes](#user-messages-the-session-writes).
 - `buildPlanNote(plan, interactionMode)` returns the note that shows the model
   the plan. The built-in loop adds it as user text before the turn's messages in every
   model call, so the model always sees the latest plan.
@@ -1286,6 +1287,107 @@ does not turn this on; pass `configOverride: { activeStepSearchMode: agentSessio
 `Client.updateFlowConfig` for a running session. See
 [Find sessions that need a person](https://docs.superdurable.io/reference/agents/approvals#find-sessions).
 
+## Showing what an approval acts on
+
+A tool approval can say what the call acts on and what it does. Its tool source returns an
+`AgentInterruptDisplay` `{ target, summary, preview? }` in `DeferredToolCall.approvalDisplay`, and the session
+stores it in `AgentInterrupt.display`, on the call's record as `approvalDisplay`, and in the `interrupt_raised`
+event. A queued ordered write raises its approval later with the display its source built when the model asked.
+
+```ts
+const snapshot = await client.invokeRPC(flow.getAgentSnapshot, sessionId);
+for (const interrupt of snapshot.pendingInterrupts) {
+  console.log(interrupt.display?.summary ?? interrupt.arguments);
+}
+```
+
+- `ConnectorToolSource` and the CLI's connector tools build it with `buildConnectorToolApprovalDisplay`: the
+  target is `<connector>/<connection>`, and the summary names the operation, the connection, and up to five short
+  arguments, such as `Calls slack postChannelMessage with connection support-slack; channel: "#eng".`
+- The CLI's local file writes name the workspace path and carry a unified diff against the file as it is when the
+  model asks; its header lines say so. Its shell commands name the working directory and the command with its
+  inline credentials redacted and its control characters escaped, cut at 2 KiB; the full command is in the call's
+  arguments.
+- A display never says how often the call runs or what it achieves, and never uses a tool's description as its
+  effect.
+- Redaction in a display is best-effort hygiene, not a security boundary. The display's text comes from the call's
+  arguments, which the session stores in full as before, and an agent can read a workspace file with its own tools.
+  A credential-like argument (`isCredentialLikeName`) shows `<redacted>`, and `redactInlineCredentials` replaces
+  common credential shapes: the value after a credential-like name, read as a shell word, a triple-quoted string, or
+  a YAML block; `Authorization` and `Cookie` header values; URL passwords; `sshpass -p`; and common token shapes.
+  It reads `\uXXXX`, `\xXX`, and `%XX` escapes to find credentials but changes no other text: escapes stay as
+  written, and only the characters of each credential become `<redacted>`. It is conservative, so a generic
+  `key=value` is redacted too, and the CLI leaves out a file preview whose text it changes. It finds common forms
+  only, and Unicode lookalike letters are out of scope; `agents/conformance/approval_display.json` lists the cases
+  both cores share.
+- The session cuts a target over `maxApprovalTargetBytes` (1 KiB) and a summary over `maxApprovalSummaryBytes`
+  (2 KiB), ending them with `…`, and drops a preview over `maxApprovalPreviewBytes` (16 KiB). A tool without a
+  display, and every approval a Worker before 0.6.0 raised, has `display` `null`: show the concrete arguments, not a
+  guessed effect.
+
+## User messages the session writes
+
+Since 0.6.0, a stored `user` message that the session wrote itself, not a person, carries
+`AgentMessage.origin`. Show such a message as a session note, or hide it, never as text the user typed.
+
+| `origin` | Message |
+| --- | --- |
+| `plan_execution` | The message with which `execute_plan` starts the turn, `buildPlanExecutionMessage(revision)` |
+| `turn_failure_note` | The note `RecordTurnFailure` stores for the model after a failed turn whose tools ran |
+| `turn_steered_note` | The note that lists the tool calls that ran before `steer_user_message` ended the turn |
+| `turn_cancelled_note` | The note that lists the tool calls that ran before `cancel_turn` ended the turn |
+
+```ts
+const page = await client.invokeRPC(flow.listAgentMessages, sessionId, { beforeSequence: null, limit: 50 });
+for (const message of page.messages) {
+  if (message.origin === "plan_execution") {
+    console.log("Running the approved plan");
+  } else if (message.origin === undefined && message.role === "user") {
+    console.log(`> ${message.text ?? ""}`);
+  }
+}
+```
+
+- Only the session sets `origin`. `send_user_message`, the start input's initial message, and a runner's messages,
+  such as a `decideTurnContinuation` message, have none.
+- The wire field is `origin`, `null` when absent; a decoded message omits it. Messages stored before 0.6.0 have
+  none. A Worker before 0.6.0 ignores the field, and drops it when it moves the message into an archive chunk.
+- A later release may add values. The decoder keeps a value it does not know, so treat any `origin` as written by
+  the session.
+
+## Listing sessions
+
+Since 0.6.0, a session can keep a summary that a session list needs: its title, the first 80 Unicode code points of
+the first user message; the time its latest turn started or ended; and its turn count. Turn it on with
+`summaryAttributesIndexed: true`; the adapter factories, such as `createBuiltinAgentSessionFlow`, take the same option.
+It is off by default, and `flow.options.summaryAttributesIndexed` tells whether a Flow keeps it. `listAgentSessions` reads one page of sessions in one `Client.searchFlows` call, without a snapshot
+per session and without a running Worker:
+
+```ts
+const flow = createAgentSessionFlow(runner, "SupportAgent", { summaryAttributesIndexed: true });
+const page = await listAgentSessions(client, flow.getFlowType(), { pageSize: 50, titleSearch: "refund" });
+for (const session of sortAgentSessionsByLastActivity(page.sessions)) {
+  console.log(session.sessionId, session.title ?? "—", session.lastActivityAt?.toISOString() ?? "—", session.turnCount);
+}
+```
+
+- Dex returns running sessions first, then the most recently closed and started ones. It cannot sort by last
+  activity, so `sortAgentSessionsByLastActivity` sorts the sessions you loaded.
+- `titleSearch` matches whole words of the title, without case: `flaky` finds "Fix the flaky test", `flak` does not.
+  Pass the same `titleSearch` with each `nextPageToken`.
+- A session without the option, or one that an earlier release started, lists without the summary, and a title search
+  never finds it. An earlier session gains the last activity time and the turn count at its next turn on a Worker with
+  the option. Show each missing value as a dash. Until a Worker with the option has started on the server, a title
+  search throws `SessionTitleSearchUnavailableError`.
+- A session that fails because its state would exceed the server's limit can keep the values of its last turn start.
+- Privacy: the title is the user's own text, and anyone who can search the namespace's Flows reads it. Turn the option
+  on only when the first message may be stored in the search index.
+- The three Attributes are indexed under `text1` (FULL_TEXT), `datetime1` (DATETIME), and `int1` (INT), the generic
+  keys that every Flow type of a namespace shares. A Worker with the option registers them when it starts. With
+  PostgreSQL search, a namespace has three keys of each of these types; the Worker fails to start with
+  `FAILED_PRECONDITION` when the namespace registered one of these keys with another type, or when all three keys of
+  the type are taken by other names. Search queries of other Flow types must filter on `FlowType`.
+
 ## Showing sessions in Dex Web
 
 Dex Web draws a session and offers its Actions from the session Flow
@@ -1418,6 +1520,9 @@ Do not repeat these tool calls unless the user asks again.
 | `PlanExecutions` | ChannelMap, key = `planExecutionKey(revision)` (decimal) | `PlanExecutionRequest { revision }` |
 | `PendingPlanExecution` | Attribute | `PlanExecutionRequest` that `execute_plan` accepted and `AwaitUserMessage` has not consumed |
 | `ContextSummary` | Attribute | `ContextSummary`, set once the session compacts |
+| `AgentSessionTitle` | Attribute, indexed FULL_TEXT `text1`; only with `summaryAttributesIndexed` | string, the first user message's title; set by the first turn only |
+| `AgentSessionLastActivityAt` | Attribute, indexed DATETIME `datetime1`; only with `summaryAttributesIndexed` | string, RFC 3339 time the latest turn started or ended |
+| `AgentSessionTurnCount` | Attribute, indexed INT `int1`; only with `summaryAttributesIndexed` | int64, `AgentState.turnCount` as of the latest turn start or end |
 | `AgentEvents` | Stream | `AgentEvent` |
 
 `AgentState.status` is `waiting_for_user_message`, `running_model`,
@@ -1457,7 +1562,7 @@ IDs are `turn-<n>`, where `n` is `turn_count + 1` when the turn starts.
 | `tool_call_deferred` | `{"tool_call_id","tool_name","effect","requires_approval"}`; the model asked for a call, which runs in its own Step |
 | `tool_call_started` | `{"tool_call_id","tool_name"}` |
 | `tool_call_finished` | `{"tool_call_id","tool_name","status"}`; the record became final, including a rejection |
-| `interrupt_raised` | `{"interrupt_id","kind","tool_call_id","tool_name","deadline","question","choices","allows_free_text"}` |
+| `interrupt_raised` | `{"interrupt_id","kind","tool_call_id","tool_name","deadline","question","choices","allows_free_text","display"}`; `display` is `{"target","summary","preview"}` or `null` |
 | `interrupt_resolved` | `{"interrupt_id","kind","approved","answered","rejection_message","cancellation_reason"}`; `answered` is `true` only for an answered question, and `cancellation_reason` is `"steered"` or `"turn_cancelled"` when steering or cancellation removed the interrupt |
 | `timer_started` | `{"tool_call_id","wait_until","reason"}` for a `durable_wait` call |
 | `plan_updated` | `{"revision","status","task_count"}` after `write_todos` replaced the plan, or when an approval marks a draft `active` |
@@ -1551,7 +1656,9 @@ server is listed again in the background while its earlier tools are
 returned. A server that cannot be listed is left out with a warning and is not
 tried again for `listingFailureBackoffMs` (30 seconds), then in the
 background, so one bad server never hides the others' tools or slows every
-model call. One listing per server runs at a time. `listTools({ refresh: true
+model call. The warnings go to `console.warn` unless `logWarning` sends them
+elsewhere, such as a log file; a `logWarning` that throws falls back to
+`console.warn`. One listing per server runs at a time. `listTools({ refresh: true
 })` lists every server again now. `deferredToolCall` stores the
 server, the tool's MCP name, and its task support on the call's record, so the
 tool Step calls that server directly, without a listing; `callTool` finds the

package/dist/src/agent-approval-display.d.ts

@@ -0,0 +1,135 @@
+import type { AgentInterruptDisplay } from "./agent-session-values.js";
+/**
+ * Largest {@link AgentInterruptDisplay.preview} the session stores, in UTF-8 bytes: 16 KiB. The session drops a
+ * longer preview and keeps the target and summary, because the display is stored on the call's record, on its
+ * interrupt, and in its `interrupt_raised` event.
+ * @since 0.6.0
+ */
+export declare const maxApprovalPreviewBytes = 16384;
+/**
+ * Largest {@link AgentInterruptDisplay.target} the session stores, in UTF-8 bytes: 1 KiB. The session cuts a longer
+ * target and ends it with `…`.
+ * @since 0.6.0
+ */
+export declare const maxApprovalTargetBytes = 1024;
+/**
+ * Largest {@link AgentInterruptDisplay.summary} the session stores, in UTF-8 bytes: 2 KiB. The session cuts a longer
+ * summary and ends it with `…`.
+ * @since 0.6.0
+ */
+export declare const maxApprovalSummaryBytes = 2048;
+/**
+ * The text an {@link AgentInterruptDisplay} shows instead of a credential.
+ * @since 0.6.0
+ */
+export declare const redactedArgumentValue = "<redacted>";
+/**
+ * Whether an argument, header, field, or variable name looks like it holds a credential, so a display shows its
+ * value as {@link redactedArgumentValue}.
+ *
+ * The name is split into words at `_`, `-`, `.`, and spaces, and again at camelCase boundaries, ignoring case, so
+ * `pAsSwOrD` is one word. It is a credential
+ * name when a word is one of `apikey`, `auth`, `authorization`, `bearer`, `cookie`, `cred`, `credential`, `dsn`,
+ * `jwt`, `key`, `otp`, `pass`, `passphrase`, `passwd`, `password`, `privatekey`, `pwd`, `secret`, `session`,
+ * `sessionid`, `signature`, or `token` (and the plural forms `apikeys`, `cookies`, `creds`, `credentials`,
+ * `passwords`, `secrets`, and `tokens`), when a word ends in `apikey`, `credential`, `credentials`, `passwd`,
+ * `password`, `secret`, `secrets`, `token`, or `tokens`, as in `PGPASSWORD`, or when it holds the words
+ * `connection string` or `conn str`. So
+ * `X-Api-Key`, `clientSecret`, `private_key`, `credentials`, and `DATABASE_CONNECTION_STRING` all match, and
+ * `channel`, `monkey`, `tokenizer`, and `author` do not. The Python core applies the same rule; the shared cases
+ * are in `agents/conformance/approval_display.json`.
+ *
+ * @example
+ * ```ts
+ * isCredentialLikeName("clientSecret"); // true
+ * isCredentialLikeName("channel"); // false
+ * ```
+ * @param name - The name to check.
+ * @returns `true` when the name looks like it holds a credential.
+ * @since 0.6.0
+ */
+export declare function isCredentialLikeName(name: string): boolean;
+/**
+ * Replaces common credential shapes written inline in a text, such as a shell command or a file, with
+ * {@link redactedArgumentValue}, and leaves every other character as it is.
+ *
+ * It is best-effort hygiene that keeps common credentials out of an approval display, not a security boundary: a
+ * credential in a form it does not know, such as one spelled with Unicode lookalike letters, stays as it is, and the
+ * call's arguments still hold the full text.
+ *
+ * It reads `\uXXXX`, `\xXX`, and `%XX` escapes as the characters they stand for, so an escaped name such as
+ * `pass\u0077ord` or `%70assword` is found, but it returns the text with the escapes as written: only the characters
+ * of each credential found are replaced. It replaces private key blocks; the password of a URL such as
+ * `https://user:pass@host`; the password of `-u user:pass`, `--user`, `--proxy-user`, and `sshpass -p`; and the value
+ * after a name that {@link isCredentialLikeName} matches, in a `name=value` assignment, a `name: value` header or
+ * field, a JSON member, or a `--name value` flag, which covers query parameters such as `?token=…`. A value runs as a
+ * shell word: backslash escapes, line continuations, and adjacent quoted parts join it, escaped quotes stay inside a
+ * quoted part, and it ends at whitespace, `&`, `;`, `,`, `}`, `]`, or `)`; an unclosed quote runs to the end of its
+ * line. A triple-quoted value runs to its closing quotes, or to the end of the text, and a YAML block scalar after
+ * `name: |` or `name: >` covers its indented lines. The value of an `Authorization` or `Cookie` header runs to the end
+ * of its line, with folded and continued lines, and its scheme, such as `Bearer`, stays. A value that is exactly
+ * {@link redactedArgumentValue} stays. Outside a header, a token-shaped word after `Bearer`, `Basic`, or `Digest` is
+ * replaced, and so are common token shapes, such as AWS access key IDs and GitHub, Slack, GitLab, and OpenAI-style
+ * keys and JWTs. The rules are conservative: a generic `key=value` is replaced too. The Python core applies the same
+ * rules; the shared cases are in `agents/conformance/approval_display.json`.
+ *
+ * @example
+ * ```ts
+ * redactInlineCredentials('curl -H "Authorization: Bearer t1" https://api.example.com?token=t1');
+ * // 'curl -H "Authorization: Bearer <redacted>" https://api.example.com?token=<redacted>'
+ * redactInlineCredentials("printf '\\x41'"); // "printf '\\x41'", unchanged
+ * ```
+ * @param text - The text.
+ * @returns The text with each credential found replaced and nothing else changed.
+ * @since 0.6.0
+ */
+export declare function redactInlineCredentials(text: string): string;
+/**
+ * The connector, connection, operation, and arguments of one connector tool call, for
+ * {@link buildConnectorToolApprovalDisplay}.
+ * @since 0.6.0
+ */
+export interface ConnectorToolApprovalDisplayInput {
+    /** The Connector ID, such as `slack`. */
+    readonly connectorId: string;
+    /** The connection's name, such as `support-slack`. */
+    readonly connectionName: string;
+    /** The operation the call runs, such as `postChannelMessage`. */
+    readonly operation: string;
+    /** The call's arguments as JSON text. */
+    readonly arguments: string;
+}
+/**
+ * Builds the approval display of one connector tool call from its operation, its connection, and its short
+ * arguments.
+ *
+ * The target is `<connectorId>/<connectionName>`. The summary names the operation and the connection and lists up to
+ * five top-level arguments in argument order: each string of at most 80 characters on one line, number, and boolean,
+ * as JSON. A credential-like argument (see {@link isCredentialLikeName}) shows {@link redactedArgumentValue} instead
+ * of its value, and string values and the connector, connection, and operation names have their inline credentials
+ * replaced (see {@link redactInlineCredentials}), as best-effort hygiene. Longer
+ * text, objects, and lists are left out; the approval UI shows them from the arguments. The summary never uses the
+ * operation's description, which says what the operation is for, not what this call does. `ConnectorToolSource` and
+ * the CLI's connector tools use it; a source of other connector tools may too.
+ *
+ * @example
+ * ```ts
+ * const display = buildConnectorToolApprovalDisplay({
+ *   connectorId: "slack",
+ *   connectionName: "support-slack",
+ *   operation: "postChannelMessage",
+ *   arguments: '{"channel":"#eng","text":"Deploy is done"}',
+ * });
+ * // display.summary: 'Calls slack postChannelMessage with connection support-slack; channel: "#eng", text: "Deploy is done".'
+ * ```
+ * @param input - The call's connector, connection, operation, and arguments.
+ * @returns The display, with no preview.
+ * @since 0.6.0
+ */
+export declare function buildConnectorToolApprovalDisplay(input: ConnectorToolApprovalDisplayInput): AgentInterruptDisplay;
+/**
+ * Returns the display the session stores for a call: `null` for none or one that is not a display; otherwise the
+ * target and summary cut to {@link maxApprovalTargetBytes} and {@link maxApprovalSummaryBytes}, and the preview, or
+ * `null` when it is over {@link maxApprovalPreviewBytes}.
+ */
+export declare function boundApprovalDisplay(display: unknown): AgentInterruptDisplay | null;