@qoniai/qoni 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qoniai/qoni",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Unified Node.js SDK for Qoni Agent delegation, GUMem memory, and WebAgent automation.",
   "homepage": "https://github.com/QONIAI/qoni-sdk-node#readme",
   "bugs": {
@@ -46,7 +46,7 @@
     "gen:event-types": "node scripts/gen-event-types.mjs",
     "typecheck": "tsc --noEmit",
     "test": "pnpm build && pnpm check:brand && pnpm test:mock && pnpm test:package",
-    "test:mock": "vitest run --coverage=false tests/qoni.test.ts tests/semantic-surface.test.ts tests/open-source-readiness.test.ts tests/complete-coverage.test.ts tests/event-catalog.test.ts tests/interactions.test.ts tests/contract-surface.test.ts tests/sse-abort.test.ts tests/do-anything-evidence.test.ts tests/query-matrix.test.ts tests/live-evidence.test.ts tests/site-login-settle-track.test.ts",
+    "test:mock": "vitest run --coverage=false tests/qoni.test.ts tests/semantic-surface.test.ts tests/open-source-readiness.test.ts tests/complete-coverage.test.ts tests/event-catalog.test.ts tests/interactions.test.ts tests/contract-surface.test.ts tests/sse-abort.test.ts tests/do-anything-evidence.test.ts tests/query-matrix.test.ts tests/live-evidence.test.ts tests/site-login-settle-track.test.ts tests/abstract-interactions.test.ts",
     "test:e2e": "QONI_LIVE_E2E=1 vitest run --coverage=false --fileParallelism=false --maxWorkers=1 --testTimeout=120000 tests/live-e2e/*.test.ts",
     "test:e2e:do-anything": "QONI_LIVE_E2E=1 vitest run --coverage=false --fileParallelism=false --maxWorkers=1 --testTimeout=120000 tests/live-e2e/do-anything.test.ts",
     "test:e2e:do-anything:release": "QONI_LIVE_E2E=1 QONI_LIVE_ALLOW_ENV_CONSTRAINTS=0 vitest run --coverage=false --fileParallelism=false --maxWorkers=1 --testTimeout=120000 tests/live-e2e/do-anything.test.ts",

package/skills/qoni-sdk/SKILL.md

@@ -66,12 +66,12 @@ const run = await qoni.doAnything.run({
 });
 const result = await run.wait({
   onScreenshot: (img, i) => saveImage(`step-${i}.jpg`, img.bytes),
-  onInputRequest: (req) => openForUser(req.liveUrl),
+  onInteraction: (handle) => handleInteraction(handle), // see "Do Anything Interactions"
 });
 console.log(result.output);
 ```
 
-For explicit authorization, the Qoni Console/BFF owns GenAuth login and grant completion before it redirects back to the business `redirectUri`. The redirect only carries one-time callback fields such as `code`, `state`, and `grant_state`/`grantId`; never design an API that exposes a delegation token to browser code.
+For explicit authorization, the Qoni Console/BFF owns GenAuth login and grant completion before it redirects back to the business `redirectUri`. The redirect only carries one-time callback fields: `code`, `grant_state`, and your business `state` when you supplied one. It does not carry `grantId`; load the `grantId` you saved by `grant_state`. Never design an API that exposes a delegation token to browser code.
 
 ```ts
 const grant = await qoni.delegateToken({
@@ -82,12 +82,17 @@ const grant = await qoni.delegateToken({
   scopes: [QoniScopes.GUMEM_MEMORY_READ],
 });
 
+// The callback carries code, state (your business state) and grant_state, but no grantId.
+await savePendingGrant(grant.data.grantState, { grantId: grant.data.grantId, businessState: "business-csrf-state" });
 redirectUserTo(grant.data.authorizationUrl);
 
+// Callback handler: look up by grant_state, check the business state, then exchange.
+const pending = await loadPendingGrant(callback.grant_state);
+if (!pending || callback.state !== pending.businessState) throw new Error("Invalid delegation callback");
 const completed = await qoni.completeDelegateToken({
-  grantId,
-  code,
-  state,
+  grantId: pending.grantId,
+  code: callback.code,
+  state: callback.grant_state,
 });
 ```
 
@@ -148,7 +153,7 @@ const run = await qoni.doAnything.run({
 run.id;
 run.sessionRef;                            // pass back to run({ session })
 await run.status();                        // refresh current state
-await run.respond(requestId, response?);   // HITL answer; omit response to skip
+run.interactionHandle(event.data);         // wrap an interaction event; answer via its methods
 await run.cancel(reason?);                 // idempotent — safe on a finished run
 
 const result = await run.wait({
@@ -156,7 +161,7 @@ const result = await run.wait({
   onEvent: (e) => console.log(e.type),
   onWireEvent: (e) => appendRawEvidence(e), // every SSE frame before semantic filtering
   onReconnect: (info) => logReconnect(info.attempt, info.lastEventId),
-  onInputRequest: (req) => openForUser(req.liveUrl),
+  onInteraction: (handle) => handleInteraction(handle), // typed InteractionHandle
   onScreenshot: (img, i) => saveImage(`step-${i}.jpg`, img.bytes),
 });
 // result: { runId, status: "succeeded"|"failed"|"canceled", output?, artifacts,
@@ -210,18 +215,38 @@ for await (const event of run.events()) {
 
 `qoni.doAnything.api.events({ token, sessionId, runId, signal?, lastEventId?, onlyTopLevel? })` yields raw `{ id?, event, data }` wire events: the type is a raw string on `event.event` (e.g. `"run.status_changed"`), the payload is `event.data.data` (snake_case), and `event.data.task_id` identifies the run. `run.status_changed` payloads carry the new status in `.to` (NOT `.status`). Terminal detection is `event.event === "run.completed"`. Wire names are internal and may evolve — prefer the high-level `run.events()` + `event.type` instead.
 
-## Do Anything Login Wall (human handoff)
+## Do Anything Interactions (human handoff)
 
-A web task often hits a page only the end user can log in to. The agent parks and emits an **`inputRequest`** event. The live-browser URL arrives on the request payload (`event.data.liveUrl`; live-url changes also stream as `progress` events with `data.liveUrl`). The client's ONLY job is to surface that URL so the human can sign in — login detection is the BACKEND's job; it re-probes and resumes the run automatically.
+When a run needs the user it pauses and emits one `interaction` event per request (`event.data` is a typed `Interaction`; `wait({ onInteraction })` hands you an `InteractionHandle`). Interactions are typed by what the user must do, never by business: `site_login`, `take_control`, `ask_user`, `confirmation`, plus the system `wait`. `switch (handle.interaction.type)` narrows `payload` per branch.
 
-- Open `liveUrl` ONCE in a real browser when you see `inputRequest`. Do NOT poll, do NOT call `respond`, do NOT wait on the window closing.
-- Keep iterating (or stay inside `wait()`); the run progresses past the wall and reaches its terminal event on its own once the user is signed in.
-- The first login is unavoidable; later runs reuse persisted login state and never reach this wall.
+- Act only on `status === "pending"` and dedupe by `interaction.id`: creation, status changes and reconnect replays all call back again with the same `id` and `type`. Updates with real content replace the card (an `active` take-over carries a new `liveUrl`); only empty settling shells keep the original `payload`.
+- Interactions arrive one at a time; the run resumes once the current one is handled.
+- `site_login`: `openLogin()` → show `liveUrl` → after the user signs in, `confirmSignedIn()` (it saves the login once, then the agent rechecks). Do NOT call the deprecated `login.confirm()` first. A `QoniError` coded `site_login.save_failed` or `site_login.session_replaced` is retryable: call `confirmSignedIn()` again. Delegate `webagent.site_login:request` and `webagent.site_login:confirm`.
+- `ask_user`: `answer(value)` with the type `payload.answerType` names (`text` string, `number`, `boolean`, `single_choice` option value, `multiple_choice` array of option values), or `skip()`. The wire's `clarification` arrives as `ask_user`; never switch on `"clarification"`.
+- `take_control`: `connectControl()` only when `handle.can("connect_control")`; it resolves to `{ liveUrl, expiresAt }` (show that URL, else `payload.liveUrl`) → `releaseControl()`. `refreshControl()` returns a fresh URL.
+- `confirmation`: `confirm()` or `reject()` after showing `payload.summary`.
+- Only call methods `handle.can(kind)` reports; an undeclared action throws.
 
 ```ts
 const result = await run.wait({
-  onInputRequest: (req) => {
-    if (req.liveUrl) openBrowserForUser(String(req.liveUrl)); // pop once; the backend resumes by itself
+  onInteraction: async (handle) => {
+    const request = handle.interaction;
+    if (request.status !== "pending" || handled.has(request.id)) return;
+    handled.add(request.id);
+    switch (request.type) {
+      case "site_login": {
+        const login = await handle.openLogin();
+        await showToUser(login.liveUrl);       // resolves when the user says "I'm signed in"
+        await handle.confirmSignedIn();
+        break;
+      }
+      case "ask_user":
+        await handle.answer(await askUser(request.payload));
+        break;
+      case "confirmation":
+        await handle.confirm();
+        break;
+    }
   },
 });
 ```
@@ -243,12 +268,9 @@ pending → running → (running ⇄ awaiting_input)* → succeeded | failed | c
   `terminal_reason` / `is_task_successful`).
 
 **Client action is event-driven, not status-driven.** The only thing that needs
-you is the `inputRequest` event (surface `liveUrl` so a human can log in /
-confirm — see Login Wall). Everything else, including login walls, the backend
-re-probes and resumes on its own. A run flapping `running ⇄ awaiting_input`
-(e.g. `waiting_reason=confirmation_required` during internal pacing) is
-expected — do NOT poll or call `respond`. Only call `respond` to answer an
-actual `inputRequest`.
+you is an `interaction` event (see Do Anything Interactions). A run flapping
+`running ⇄ awaiting_input` (e.g. `waiting_reason=confirmation_required` during
+internal pacing) is expected — do NOT poll; act only on pending interactions.
 
 ### Parent & sub-tasks