@raidiant/notifai 11.6.3-beta.2 → 11.7.0-beta.2

package/dist/skill-source/notifai/references/harness-setup.md

@@ -14,23 +14,31 @@ diagnosing, or recovering — not before.
 
 ## Signing this machine in
 
-Run `notifai init --json` yourself. When this machine is not paired it starts
-one approval, opens the approval page only the User can approve if a browser
-is reachable, polls once, and returns: progress is on stderr, final readiness
-on stdout, and the `credential` state's `technical.pairing` holds the
-`approve_url` and `code`.
-Tell the User to open that page, check the code, and approve — in the fixed
-T2 wording of <https://app.notifai.sh/setup.md>, which also names the other
-handoffs (denied, expired, no access, companion app, hook trust); when they
-say so, run the same command again. It resumes the approval it started — the
-handshake is kept on this machine until it resolves or expires — so a tool
-timeout or a closed shell never strands an approval the User already gave. A
-new code on a later run means the earlier approval expired; relay the new one.
-
-`notifai login --no-open` starts or resumes the same approval without opening
-a browser. `--name <name>` sets what the machine is called in their dashboard;
-the hostname is the default. `notifai logout` discards a saved credential and
-any approval still waiting.
+Run `notifai init --json` yourself. An unapproved Machine starts one approval,
+defaults to QR without asking for email, polls once, and returns. Progress is
+on stderr and final readiness on stdout. The `credential` state's
+`technical.pairing` holds protected local `qr_path` and `qr_text_path` artifacts,
+the `approve_url`, and matching `code`. Present the QR before requesting a scan:
+show the local image where supported, or read `qr_text_path` and reproduce the
+library-generated QR verbatim in a fenced text block in a terminal/text-only harness.
+Display the matching code beside it. Never include the QR
+or proof-bearing link in any Notification Request field or media. Use T2 from
+<https://app.notifai.sh/setup.md>: the User reviews their Account, computer, and
+matching code in their signed-in Companion App before approving. A valid Auth
+Session needs no additional email code merely to approve a Machine. Only the User can approve; opening review never approves automatically.
+If the harness cannot display the local QR, present the browser alternative
+truthfully rather than claiming a QR was shown.
+
+Only when the User chooses an approval notification, ask for their Account
+email; never infer it from other services or files. Run `notifai init --approval notification --approval-email <email>
+--json`. Requested delivery is not confirmed delivery. For the browser
+alternative use `--approval browser`; it opens no browser by default. Every
+route resumes the same pending approval. When the User says it is approved,
+run setup again. If it reports a new code, relay that code. A timeout or closed
+shell does not strand an approval already given.
+
+`--name <name>` sets the Machine name; the hostname is the default.
+`notifai logout` discards the saved credential and any pending approval and QR.
 
 `notifai auth status --json` says whether this machine is paired.
 `notifai auth access --json` says whether the account has access, including
@@ -263,13 +271,18 @@ meter differs per harness:
   Direct inbox wake is unavailable, but it is not needed while this exact Stop
   continuation owns the answer.
 - **Codex:** a detached observer starts after submission and waits in the
-  background for the complete answer window; Stop provides recovery. When an answer arrives, Notifai
-  invokes `codex queue` for the exact Agent Session in the same Codex home.
-  Only a wake-up is queued. Pending notes and answers remain in Notifai until
+  background for the complete answer window; Stop provides recovery. While a
+  trusted tool hook can hand input into a working turn, Notifai uses that hook.
+  Idle sessions, or sessions whose live input path cannot be established, use
+  a content-free wake for the exact Agent Session in the same Codex home.
+  Notifai does not cold-start or resume Codex to obtain a control connection.
+  Pending notes and answers remain in Notifai until
   a trusted tool hook, prompt hook, or `notifai receive` drains a bounded batch.
   A late wake-up cannot repeat an acknowledged answer: it contains no answer
   text. Queue success proves wake storage, not input presentation. Inputs are
   claimed immediately before presentation; uncertain writes are never replayed.
+  Verified queue control can remove a stale wake owned by Notifai; unavailable
+  control leaves the harmless wake in place and preserves human prompts.
   Keep the original question and request identities when investigating a delay.
 - **Grok:** the Stop hook stays held through the complete answer window and
   returns the answer as a decision block to the same Agent Session. Its native

package/dist/skill-source/notifai/references/native-questions.md

@@ -0,0 +1,51 @@
+# Native questions linked to Notifai
+
+Use this flow only when `ask` returns `native_question`. Native forms are
+optional; Question Routing still works without them. New linking requires both
+local eligibility and confirmed service support. Capability absence leaves
+the ordinary conversation and app-answer flow available.
+
+## Before emitting the form
+
+Use the returned tool, titles and options exactly, in the registration turn.
+The short title marker identifies a registered question; wording alone does
+not. Keep the returned question and choice IDs for reporting its answer.
+An unsupported form or missing binding stays ordinary. Preserve unrelated
+native forms, even when they contain identical wording.
+
+## When the native answer arrives
+
+Read the actual native answer. As the first command before work depending on
+that answer, run the `notifai acknowledge q_…` command printed by `ask`, filling
+in the actual answer IDs or typed text and an authored acknowledgement naming
+the concrete work it causes. Report partial answers as partial: only include
+questions the User answered. An app answer relayed through a native envelope
+keeps its printed app acknowledgement command; do not report it as a new
+native submission.
+
+`--native-answers` accepts an array: a choice answer looks like
+`[{"question_id":"q1","choice_ids":["staging"]}]`; a typed answer looks like
+`[{"question_id":"q1","text":"Wait until tomorrow"}]`. Substitute the actual
+returned question/choice IDs and the User's actual words.
+
+Choose a distinct operation ID for each distinct native submission. Retrying
+the same submission uses the same operation ID, answers and acknowledgement.
+An identity-only retry is valid only after the command confirms it saved the
+operation. Follow its recovery output when submission or acknowledgement is
+unconfirmed; keep the original question instead of registering another one.
+
+Success confirms that the native answer and authored acknowledgement were
+recorded. Review `other_submissions` before acting. Preserve distinct app and
+native answers; a conflict needs clarification before further dependent work.
+An already acknowledged operation must not repeat work it previously caused.
+
+Keep the original app answer watcher after native acknowledgement: a reply may
+already be in flight, and the User can still answer within its original window.
+Use `close` for explicit withdrawal, not as native-answer acknowledgement.
+If you never emitted the exact returned form, an ordinary conversation answer
+still uses the unlinked question's `close` flow.
+
+Reporting an answer does not prove a native form closed. Native settlement
+depends on the harness capabilities and exact binding; missing or uncertain
+control must leave unrelated forms untouched. Describe only the result the
+command actually confirms.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raidiant/notifai",
-  "version": "11.6.3-beta.2",
+  "version": "11.7.0-beta.2",
   "type": "module",
   "description": "Send native device notifications from agents and local programs",
   "bin": {
@@ -12,13 +12,20 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@raidiant/notifai-protocol": "8.1.5",
+    "@raidiant/notifai-protocol": "8.2.0-beta.2",
     "commander": "^14.0.0",
     "jsonc-parser": "^3.3.1",
     "picocolors": "^1.1.1",
-    "smol-toml": "^1.4.0"
+    "qrcode": "1.5.4",
+    "smol-toml": "^1.4.0",
+    "ws": "8.21.0"
   },
   "devDependencies": {
+    "@types/pngjs": "6.0.5",
+    "@types/qrcode": "1.5.6",
+    "@types/ws": "8.18.1",
+    "jsqr": "1.4.0",
+    "pngjs": "7.0.0",
     "typescript": "^5.8.0",
     "vitest": "4.1.11"
   },