waku-memory 0.3.0 → 0.4.1

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "waku",
-  "version": "0.3.0",
-  "description": "Waku Memory: durable memory for your Codex sessions. memory.recall brings what is known about a project into a session; memory.remember keeps what matters; the plugin's hooks open each session with a brief and send each turn to be remembered.",
+  "version": "0.4.1",
+  "description": "Waku Memory: durable memory for your Codex sessions. memory.recall brings what is known about a project into a session; memory.remember keeps what matters; the plugin's hooks open each session with a brief and send each turn to be remembered. What you type and what the agent replies is sent to Waku's servers and on to Anthropic, which is what turns a session into memories; your files, the commands the agent runs and its reasoning are not. This is an alpha and its data can be lost.",
   "skills": "./skills/",
   "hooks": "./hooks/hooks.json",
   "interface": {

package/dist/capture.js

@@ -252,6 +252,15 @@ export function hookInvocation(execPath, indexPath) {
 // Codex-only machine has no other way to learn that the same three hooks
 // exist there too, or that installing the Waku plugin instead is the other
 // route to the same events (codexPluginPresent, this file's own enable()).
+//
+// This text now exists in four places with no mechanism sharing it (found
+// 2026-09-10, status.md item 9's dated paragraph): this DISCLOSURE, the
+// Codex plugin manifest's "description" (.codex-plugin/plugin.json, pinned
+// by plugin.test.mjs), skills/waku/SKILL.md's "sent to Waku" bullet, and
+// the frontend's OAuth consent page (waku-memory-frontend
+// app/oauth/consent/page.tsx, its CONSENT_DISCLOSURE constant). A change to
+// the two facts here -- where captured content goes, and that this is an
+// alpha -- has to be carried to the other three by hand.
 export const DISCLOSURE = 'Captured content is sent to our servers and to Anthropic for extraction. ' +
     'This is an alpha whose data can be lost. ' +
     'What you type, what the agent replies, and the names of the tools it uses are sent; ' +

package/dist/cli.js

@@ -133,6 +133,10 @@ export function printUsage() {
     console.log(`  --name  key to add under mcpServers (default: "${DEFAULT_NAME}")`);
     console.log(`  --url   server URL to write (default: ${DEFAULT_URL})`);
     console.log('');
+    console.log('  If a harness was found, setup then asks whether to also turn on automatic');
+    console.log('  capture -- the same flow as "capture enable", asked so you do not have to');
+    console.log('  type a second command. Default is no; press Enter to skip it.');
+    console.log('');
     console.log('Usage: waku-memory hook [--harness <claude_code|codex>]');
     console.log('');
     console.log('  Reads one hook event as JSON on stdin and reports it to the server named');
@@ -464,13 +468,49 @@ export function summarize(results) {
         hadError: results.some((r) => r.status === 'error'),
     };
 }
-export function setup(name, url, harnesses = getHarnesses(), 
+// The one-shot readline prompt setup()'s own new question needs, real
+// default for SetupPrompt below -- a plain rl.question(), not the
+// async-iterator dance runCaptureCommand's own prompt uses for enable()'s
+// two sequential questions (see that function's own comment): setup() only
+// ever asks one question of its own before handing off to runCaptureEnable,
+// which opens (and closes) its own readline in turn, so there is no shared
+// interface for two overlapping .question() calls to race over.
+function realSetupPrompt(question) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+// Verbatim -- cli.test.mjs depends on this exact string, the same contract
+// capture.ts's own SIGN_IN_QUESTION carries.
+export const TURN_ON_CAPTURE_QUESTION = 'Also turn on automatic capture? It sends what you type and what the agent replies to Waku. [y/N]: ';
+export async function setup(name, url, harnesses = getHarnesses(), 
 // R20 (final review, spec 012): the real default, injected the same way
 // realCaptureDeps below builds it -- so cli.test.mjs can point this at a
 // temp path instead of the machine's actual ~/.codex/config.toml, the
 // same reason every other real path in this file is a parameter with a
 // real default rather than a bare homedir() call inline.
-codexConfigPath = join(homedir(), '.codex', 'config.toml')) {
+codexConfigPath = join(homedir(), '.codex', 'config.toml'), 
+// The two additions that make setup() async (this task): the question
+// itself (realSetupPrompt, above) and what a "y" answer actually runs.
+// Both injectable, the same reason every real path/writer/fetch in this
+// file is a parameter with a real default rather than a bare call inline
+// -- so cli.test.mjs never opens real stdin and never runs a real
+// capture enable. The real runCaptureEnable below is nothing but the
+// existing "capture enable" command path (runCaptureCommand, same as
+// dispatch()'s own 'capture'/'enable' case), called with no flags -- the
+// Sign-in question, enable()'s own disclosure and typed "y" gate, the
+// credential step, the hooks, and the bootstrap question all run exactly
+// as they do from the command line. Nothing here may skip, weaken, or
+// pre-answer any of that: the only thing this buys the person is not
+// having to type "npx waku-memory capture enable" a second time.
+prompt = realSetupPrompt, runCaptureEnable = () => {
+    const { ingestUrl, mcpUrl } = urlPair(url);
+    return runCaptureCommand('enable', ingestUrl, mcpUrl, DEFAULT_BOOTSTRAP, { kind: 'ask' });
+}) {
     const results = runSetup(harnesses, name, url);
     for (const r of results) {
         if (r.status === 'error')
@@ -523,6 +563,20 @@ codexConfigPath = join(homedir(), '.codex', 'config.toml')) {
     }
     if (hadError)
         process.exitCode = 1;
+    // The new question this task adds: asked only once there is something to
+    // turn capture on for -- a machine with no harness found has nothing for
+    // "capture enable" to install into either, so asking would just repeat
+    // the "nothing was added" message above in question form. Default is no
+    // (an empty answer, from pressing Enter, keeps today's behaviour exactly)
+    // -- capture is a much bigger step than writing an MCP config, so unlike
+    // enable()'s own SIGN_IN_QUESTION (whose default path still requires
+    // choosing 1 or 2), this one must never be opted into by accident.
+    if (foundAny) {
+        const answer = (await prompt(TURN_ON_CAPTURE_QUESTION)).trim().toLowerCase();
+        if (answer === 'y') {
+            await runCaptureEnable();
+        }
+    }
 }
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
@@ -822,7 +876,10 @@ export function run(argv) {
             process.exitCode = 1;
             return;
         case 'setup':
-            setup(d.name, d.url);
+            void setup(d.name, d.url).catch((err) => {
+                console.error(`waku-memory setup: unexpected failure -- ${errorMessage(err)}.`);
+                process.exitCode = 1;
+            });
             return;
         case 'login':
             // Ruling R15: the disclosure (and a blank line), no y/n gate -- unlike

package/dist/hook.js

@@ -63,7 +63,7 @@ export { SESSION_END_HOOK_TIMEOUT_S, SESSION_END_TIMEOUT_MS } from "./harnesses.
 // hook.test.mjs's drift check (against package.json) both need it; task 14
 // (spec 012 §9) bumps this, package.json and the plugin manifest
 // (.codex-plugin/plugin.json) to 0.3.0 together.
-export const SHIM_VERSION = '0.3.0';
+export const SHIM_VERSION = '0.4.1';
 // Exported for capture.ts, which writes the file this module reads.
 export const CONFIG_FILE_NAME = 'config.json';
 // Same-directory temp file + rename, exactly atomicWriteJson's technique in

package/dist/login.js

@@ -33,7 +33,122 @@ export const LOGIN_SCOPES = 'openid profile email offline_access';
 // default apiBase, so a reader (or a test asserting against the default)
 // has something to compare the runtime value to without recomputing it.
 export const LOGIN_RESOURCE = 'https://api.waku.one/mcp';
-const REGISTERED_REDIRECT_URI = 'http://127.0.0.1/callback';
+const CALLBACK_PAGE_COPY = {
+    // The real success. Only this one gets the ok/accent treatment -- the
+    // system's own message vocabulary (§14 of the design doc) marks a
+    // level with an uppercase mono word before the sentence, not with a
+    // filled surface or an icon.
+    'signed-in': {
+        title: 'Signed in',
+        mark: 'OK',
+        markColor: 'var(--ok)',
+        heading: 'Signed in.',
+        body: 'This tab can be closed now.',
+    },
+    // The duplicate callback (`accepted` already true): the flow already
+    // finished, so this is not an error and carries no color.
+    'already-signed-in': {
+        title: 'Already signed in',
+        mark: '·',
+        markColor: 'var(--text-faint)',
+        heading: 'Already signed in.',
+        body: 'Nothing else to do here.',
+    },
+    // The `state` mismatch or missing `code` (400). Neither an ok nor a
+    // plain neutral: a mismatched state can mean the link was tampered
+    // with, so this reads as the doc's `warn` level -- worth noticing,
+    // not a failure to panic over -- and says the one thing that is a
+    // different action from reloading this tab: go back to the terminal.
+    'could-not-complete': {
+        title: 'Sign-in could not complete',
+        mark: 'WARN',
+        markColor: 'var(--warn)',
+        heading: 'Sign-in did not complete.',
+        body: 'The command is still running. Try again from the terminal.',
+    },
+    // Any path but /callback (404). Nothing to explain beyond the one fact.
+    'not-found': {
+        title: 'Not found',
+        mark: '·',
+        markColor: 'var(--text-faint)',
+        heading: 'Not found.',
+        body: 'This address is not part of sign-in.',
+    },
+};
+function renderCallbackPage(state) {
+    const copy = CALLBACK_PAGE_COPY[state];
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${copy.title}</title>
+<style>
+  :root {
+    --ground: #E1E1D9;
+    --ink: #161614;
+    --accent-ink: #161614;
+    --ok: #2B7754;
+    --warn: #8C5617;
+    --text-muted: color-mix(in srgb, var(--ink) 82%, var(--ground));
+    --text-faint: color-mix(in srgb, var(--ink) 62%, var(--ground));
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --ground: #202020;
+      --ink: #C9CDD1;
+      --ok: #4FBF8B;
+      --warn: #E78B23;
+    }
+  }
+  * { box-sizing: border-box; }
+  html, body { height: 100%; margin: 0; }
+  body {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 24px;
+    background: var(--ground);
+    color: var(--ink);
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+    font-weight: 400;
+    text-align: center;
+  }
+  main { max-width: 40ch; }
+  .mark {
+    display: block;
+    margin: 0 0 12px;
+    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    font-weight: 500;
+    font-size: 12px;
+    letter-spacing: .16em;
+    text-transform: uppercase;
+    color: ${copy.markColor};
+  }
+  h1 {
+    margin: 0 0 12px;
+    font-size: 20px;
+    font-weight: 500;
+    line-height: 1.3;
+  }
+  p {
+    margin: 0;
+    font-size: 15px;
+    line-height: 1.5;
+    color: var(--text-muted);
+  }
+</style>
+</head>
+<body>
+<main>
+<span class="mark">${copy.mark}</span>
+<h1>${copy.heading}</h1>
+<p>${copy.body}</p>
+</main>
+</body>
+</html>
+`;
+}
 // Carries which of the four network steps failed and the HTTP status that
 // said so -- login()'s refusal branches read both off this and print
 // neither a response body nor anything from the request (never the token,
@@ -83,18 +198,25 @@ export async function discover(apiBase, fetchImpl) {
         registrationEndpoint: registration_endpoint,
     };
 }
-// Dynamic client registration (RFC 7591): a public client, redirect fixed
-// at the bare loopback address (RFC 8252 §7.3 -- the *port* login actually
-// redirects to is chosen per run and never registered, which is the whole
-// point of the loopback exception). Returns client_id; throws
-// StepError('registration', status) otherwise.
-export async function registerClient(registrationEndpoint, fetchImpl, version) {
+// Dynamic client registration (RFC 7591): a public client, registered with
+// the exact redirect URI login() will use for the authorize request and the
+// token exchange -- including the ephemeral port the loopback listener is
+// actually on. RFC 8252 §7.3 lets a client register the bare loopback
+// address and redirect to any port at request time, but our authorization
+// server (Supabase) exact-matches redirect_uri against what was registered
+// and does not implement that exception (measured against the deployed
+// service, 2026-09-08: registering the bare address and then authorizing
+// against the real port got back `{"error_code":"validation_failed","msg":
+// "invalid redirect_uri"}`). So the caller must start the listener first and
+// pass its real redirect URI in here -- see login()'s own ordering. Returns
+// client_id; throws StepError('registration', status) otherwise.
+export async function registerClient(registrationEndpoint, fetchImpl, version, redirectUri) {
     const res = await fetchImpl(registrationEndpoint, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
             client_name: `waku-memory ${version}`,
-            redirect_uris: [REGISTERED_REDIRECT_URI],
+            redirect_uris: [redirectUri],
             grant_types: ['authorization_code'],
             response_types: ['code'],
             token_endpoint_auth_method: 'none',
@@ -187,10 +309,20 @@ function reportRefusal(deps, fallbackStep, err) {
 // only things written to deps.stdout are the authorize URL, the final
 // "Signed in as <email>" line, and (on refusal) the one-line step/status
 // report above. The loopback server, once opened, is closed on every path
-// out of the returned promise: 'signed-in', 'timeout', and 'refused' from
-// a bad token or keys response all go through the same finish().
-// 'refused' from discovery or registration returns before any server
-// exists, so there is nothing to close on those two paths.
+// out of the returned promise: 'signed-in', 'timeout', and 'refused' from a
+// listener failure, a bad registration, or a bad token/keys response all go
+// through the same finish(). 'refused' from discovery returns before any
+// server exists, so there is nothing to close on that one path.
+//
+// Ordering (fixed 2026-09-08, measured against the deployed service): the
+// listener starts FIRST, before registration, so registerClient can be
+// given the real `http://127.0.0.1:<port>/callback` -- the same string then
+// used, unchanged, for the authorize URL and the token exchange. Registering
+// the bare loopback address ahead of knowing the port (the previous order)
+// is what RFC 8252 §7.3 expects a server to accept via its any-port
+// exception, but Supabase exact-matches redirect_uri against the registered
+// list and answered with `invalid redirect_uri`: see registerClient's own
+// comment for the exact response.
 export async function login(deps) {
     const apiBase = stripSlash(deps.apiBase);
     const resource = `${apiBase}/mcp`;
@@ -203,25 +335,18 @@ export async function login(deps) {
         reportRefusal(deps, 'discovery', err);
         return 'refused';
     }
-    let clientId;
-    try {
-        clientId = await registerClient(discovered.registrationEndpoint, deps.fetchImpl, deps.version);
-    }
-    catch (err) {
-        reportRefusal(deps, 'registration', err);
-        return 'refused';
-    }
     const { verifier, challenge } = pkce();
     const state = randomBytes(16).toString('hex');
     return new Promise((resolveLogin) => {
         let settled = false;
-        let port = 0;
         let accepted = false;
+        let clientId = '';
+        let redirectUri = '';
         const server = createServer((req, res) => {
             const requestUrl = new URL(req.url ?? '/', 'http://127.0.0.1');
             if (requestUrl.pathname !== '/callback') {
-                res.writeHead(404);
-                res.end();
+                res.writeHead(404, { 'Content-Type': 'text/html' });
+                res.end(renderCallbackPage('not-found'));
                 return;
             }
             const code = requestUrl.searchParams.get('code');
@@ -230,8 +355,8 @@ export async function login(deps) {
                 // Wrong or missing state: keep waiting -- a stray or forged hit on
                 // this port must not end the flow the real browser is still
                 // carrying.
-                res.writeHead(400);
-                res.end();
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end(renderCallbackPage('could-not-complete'));
                 return;
             }
             // OAuth codes are single-use and minting a credential should be
@@ -241,12 +366,12 @@ export async function login(deps) {
             // sees the flag and returns 200 without re-running the exchange.
             if (accepted) {
                 res.writeHead(200, { 'Content-Type': 'text/html' });
-                res.end('Signed in. You can close this tab.');
+                res.end(renderCallbackPage('already-signed-in'));
                 return;
             }
             accepted = true;
             res.writeHead(200, { 'Content-Type': 'text/html' });
-            res.end('Signed in. You can close this tab.');
+            res.end(renderCallbackPage('signed-in'));
             void finishSignIn(code);
         });
         const finish = (result) => {
@@ -254,12 +379,25 @@ export async function login(deps) {
                 return;
             settled = true;
             clearTimeout(timer);
+            // server.close() alone only stops accepting *new* connections; it
+            // waits for existing ones to end on their own before the server (and
+            // its socket handles) actually goes away. A real browser holds the
+            // callback connection open with HTTP keep-alive -- it never ends the
+            // connection itself -- so that lone open socket kept the event loop
+            // alive and the process never exited (measured 2026-09-08 against
+            // the deployed service: a real sign-in completed, config.json was
+            // written, and the process was still running 92s later). Dropping
+            // every outstanding connection here, active or idle, is what lets
+            // the server -- and the process -- actually finish closing, on every
+            // path through finish(): signed-in, timeout, and refused alike.
+            // closeAllConnections() has been available since Node 18.2; this
+            // package requires Node >=20 (see package.json's engines).
             server.close();
+            server.closeAllConnections();
             resolveLogin(result);
         };
         async function finishSignIn(code) {
             try {
-                const redirectUri = `http://127.0.0.1:${port}/callback`;
                 const tokenResult = await exchangeToken(discovered.tokenEndpoint, deps.fetchImpl, {
                     code,
                     redirectUri,
@@ -293,20 +431,41 @@ export async function login(deps) {
             }
         }
         const timer = setTimeout(() => finish('timeout'), timeoutMs);
+        // A listener that never comes up (EADDRINUSE, permissions, ...) fires
+        // 'error' instead of the 'listening' callback below -- reported the same
+        // way every other step is, naming 'listener' rather than falling through
+        // to a confusing StepError from somewhere else.
+        server.on('error', (err) => {
+            reportRefusal(deps, 'listener', err);
+            finish('refused');
+        });
         server.listen(0, '127.0.0.1', () => {
             const address = server.address();
-            port = typeof address === 'object' && address !== null ? address.port : 0;
-            const redirectUri = `http://127.0.0.1:${port}/callback`;
-            const url = authorizeUrl({
-                authorizationEndpoint: discovered.authorizationEndpoint,
-                clientId,
-                redirectUri,
-                state,
-                challenge,
-                resource,
+            const port = typeof address === 'object' && address !== null ? address.port : 0;
+            if (port === 0) {
+                reportRefusal(deps, 'listener', new Error('the loopback listener did not report a port'));
+                finish('refused');
+                return;
+            }
+            redirectUri = `http://127.0.0.1:${port}/callback`;
+            registerClient(discovered.registrationEndpoint, deps.fetchImpl, deps.version, redirectUri)
+                .then((id) => {
+                clientId = id;
+                const url = authorizeUrl({
+                    authorizationEndpoint: discovered.authorizationEndpoint,
+                    clientId,
+                    redirectUri,
+                    state,
+                    challenge,
+                    resource,
+                });
+                deps.stdout(`Open this URL if your browser did not: ${url}`);
+                deps.openBrowser(url);
+            })
+                .catch((err) => {
+                reportRefusal(deps, 'registration', err);
+                finish('refused');
             });
-            deps.stdout(`Open this URL if your browser did not: ${url}`);
-            deps.openBrowser(url);
         });
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waku-memory",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Install Waku Memory into your agent harness, and turn on automatic session capture.",
   "keywords": ["mcp", "memory", "claude-code", "agent", "waku"],
   "homepage": "https://github.com/ShenSeanChen/waku-memory-backend/tree/spec-driven/shim#readme",

package/skills/waku/SKILL.md

@@ -16,8 +16,17 @@ learn, and brings it back into later sessions.
   a procedure or a fact they will want next time. Use their words. Do not
   store secrets, credentials or file contents.
 - What the person types and what you reply is sent to Waku after each turn
-  by the plugin's hooks; tool output is not.
+  by the plugin's hooks; tool output is not. It goes on to Anthropic, which
+  is what turns a session into memories. This is an alpha and its data can
+  be lost.
 
 One-time setup the person does: after installing, Codex asks them to
 review and trust this plugin's hooks (`/hooks` in the CLI). Until then
 the brief and the capture do not run.
+
+<!-- This bullet's two facts (where captured content goes, and that this
+     is an alpha) also live in capture.ts's DISCLOSURE, the Codex plugin
+     manifest's "description" (.codex-plugin/plugin.json), and the
+     frontend's OAuth consent page (waku-memory-frontend
+     app/oauth/consent/page.tsx's CONSENT_DISCLOSURE). No mechanism shares
+     the string; a change here has to be carried to the other three. -->