nofax 0.2.3 → 0.2.5

package/README.md

@@ -11,7 +11,7 @@ Nofax is a small open-source bridge between an agent and a human. Local mode can
 
 No Nofax account. No paid model API. No inbound port on your machine. MIT licensed.
 
-> **Current status:** local Nofax is `0.2.1`. The optional Cloudflare Worker is the upcoming `0.3.0` remote surface and is developed alongside the local package.
+> **Current status:** local Nofax is on the stable `0.2.x` line. The optional Cloudflare Worker is the upcoming `0.3.0` remote surface and is developed alongside the local package.
 
 ## Why Nofax
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nofax",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "mcpName": "io.github.AKzar1el/nofax",
   "description": "Human-in-the-loop approvals and notifications for AI coding agents via CLI, MCP, and agent hooks.",
   "type": "module",

package/src/mcp-server.mjs

@@ -30,9 +30,51 @@ function result(value) {
   };
 }
 
+const OUTPUT_REQUEST_ID = z.string().min(24).max(84).describe('Durable Nofax request handle.');
+
+const PENDING_OUTPUT_SCHEMA = z.object({
+  status: z.literal('pending').describe('The request is unresolved and must not be treated as approval.'),
+  requestId: OUTPUT_REQUEST_ID,
+  mustWait: z.literal(true).describe('Signals that the caller must keep waiting for a terminal human response.'),
+  instruction: z.string().min(1).describe('Fail-closed next-step instruction for the caller.')
+});
+
+const WAIT_OUTPUT_SCHEMA = z.object({
+  status: z.enum(['pending', 'resolved']).describe('Whether the human request is still pending or has reached a terminal response.'),
+  requestId: OUTPUT_REQUEST_ID,
+  mustWait: z.boolean().optional().describe('Present and true while the request remains pending.'),
+  decision: z.string().min(1).max(80).optional().describe('Terminal human decision when resolved, such as allow, deny, refine, or an explicit choice value.'),
+  text: z.string().min(1).max(2000).optional().describe('Human free-text refinement when the terminal decision is refine.'),
+  instruction: z.string().min(1).describe('Safety-preserving instruction describing what the caller may do next.')
+});
+
+const PUBLIC_REQUEST_SCHEMA = z.object({
+  requestId: OUTPUT_REQUEST_ID,
+  kind: z.enum(['approval', 'choice', 'refinement']).describe('Interaction mode that created the durable request.'),
+  status: z.enum(['pending', 'resolved']).describe('Current durable request state.'),
+  createdAt: z.string().min(1).describe('ISO-8601 creation timestamp.'),
+  resolvedAt: z.string().min(1).optional().describe('ISO-8601 terminal-response timestamp when resolved.'),
+  decision: z.string().min(1).max(80).optional().describe('Terminal human decision when resolved.'),
+  text: z.string().min(1).max(2000).optional().describe('Human refinement text when one was supplied.')
+});
+
+const NOTIFY_OUTPUT_SCHEMA = z.object({
+  status: z.literal('sent').describe('The notification transport call completed successfully; this is never approval.')
+});
+
+const GET_REQUEST_OUTPUT_SCHEMA = z.object({
+  status: z.literal('ok').describe('The durable request was read successfully.'),
+  request: PUBLIC_REQUEST_SCHEMA.describe('Safe request metadata and terminal state; secret response topics are omitted.')
+});
+
+const LIST_PENDING_OUTPUT_SCHEMA = z.object({
+  status: z.literal('ok').describe('The pending-request scan completed successfully.'),
+  requests: z.array(PUBLIC_REQUEST_SCHEMA).describe('Bounded unresolved request projections with no secret response topics.')
+});
+
 export function buildMcpServer({ handlers = createMcpToolHandlers() } = {}) {
   const server = new McpServer(
-    { name: 'nofax', version: '0.2.3' },
+    { name: 'nofax', version: '0.2.5' },
     { instructions: SERVER_INSTRUCTIONS }
   );
 
@@ -40,11 +82,12 @@ export function buildMcpServer({ handlers = createMcpToolHandlers() } = {}) {
     'nofax_notify',
     {
       title: 'Send Nofax notification',
-      description: 'Send a one-way phone notification. This tool is informational and does not create a human-response wait.',
+      description: 'Send a one-way phone notification. This tool is informational and does not create a human-response wait. Notification transport success never counts as approval.',
       inputSchema: z.object({
-        title: z.string().min(1).max(120).optional(),
-        message: z.string().min(1).max(2200)
+        title: z.string().min(1).max(120).optional().describe('Optional notification title shown to the human; defaults to "Nofax".'),
+        message: z.string().min(1).max(2200).describe('Notification body shown to the human.')
       }),
+      outputSchema: NOTIFY_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
     },
     async (args) => result(await handlers.notify(args))
@@ -56,10 +99,11 @@ export function buildMcpServer({ handlers = createMcpToolHandlers() } = {}) {
       title: 'Request human approval',
       description: 'Send Allow/Deny to the phone and return a durable pending requestId. IMPORTANT: after this tool returns pending, call nofax_wait_for_response and repeat while it remains pending. Never continue the guarded action without a terminal Allow response. Set allowRefine when the human should also be able to send refinement text.',
       inputSchema: z.object({
-        title: z.string().min(1).max(120).optional(),
-        message: z.string().min(1).max(2200),
-        allowRefine: z.boolean().optional()
+        title: z.string().min(1).max(120).optional().describe('Optional approval prompt title shown to the human; defaults to "Nofax approval".'),
+        message: z.string().min(1).max(2200).describe('Guarded action or decision context shown to the human.'),
+        allowRefine: z.boolean().optional().describe('When true, also let the human return free-text refinement instead of only Allow or Deny.')
       }),
+      outputSchema: PENDING_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
     },
     async (args) => result(await handlers.requestApproval(args))
@@ -71,13 +115,17 @@ export function buildMcpServer({ handlers = createMcpToolHandlers() } = {}) {
       title: 'Request human choice',
       description: 'Send up to three explicit options to the phone and return a durable pending requestId. IMPORTANT: call nofax_wait_for_response and repeat while pending; do not choose on the human\'s behalf.',
       inputSchema: z.object({
-        title: z.string().min(1).max(120).optional(),
-        message: z.string().min(1).max(2200),
+        title: z.string().min(1).max(120).optional().describe('Optional choice prompt title shown to the human; defaults to "Nofax choice".'),
+        message: z.string().min(1).max(2200).describe('Question or decision context shown to the human.'),
         options: z.array(z.union([
-          z.string().min(1).max(80),
-          z.object({ value: z.string().min(1).max(80), label: z.string().min(1).max(32) })
-        ])).min(1).max(3)
+          z.string().min(1).max(80).describe('String shorthand for a choice value; its first 32 characters are also used as the human-facing label.'),
+          z.object({
+            value: z.string().min(1).max(80).describe('Choice value returned as the terminal human decision.'),
+            label: z.string().min(1).max(32).describe('Short human-facing label displayed for this choice.')
+          })
+        ])).min(1).max(3).describe('One to three explicit choices to present to the human.')
       }),
+      outputSchema: PENDING_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
     },
     async (args) => result(await handlers.requestChoice(args))
@@ -89,9 +137,10 @@ export function buildMcpServer({ handlers = createMcpToolHandlers() } = {}) {
       title: 'Request human refinement',
       description: 'Ask the human for free-text refinement through the configured Nofax Refine iOS Shortcut. Returns a durable pending requestId. IMPORTANT: call nofax_wait_for_response and repeat while pending.',
       inputSchema: z.object({
-        title: z.string().min(1).max(120).optional(),
-        message: z.string().min(1).max(2200)
+        title: z.string().min(1).max(120).optional().describe('Optional refinement prompt title shown to the human; defaults to "Nofax refinement".'),
+        message: z.string().min(1).max(2200).describe('Context or draft the human should refine with free text.')
       }),
+      outputSchema: PENDING_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
     },
     async (args) => result(await handlers.requestRefinement(args))
@@ -103,9 +152,10 @@ export function buildMcpServer({ handlers = createMcpToolHandlers() } = {}) {
       title: 'Wait for Nofax human response',
       description: 'Long-poll a durable Nofax request for up to 240 seconds. If the result is pending, you MUST call this tool again with the same requestId. Repeat indefinitely until a terminal response is returned or the user explicitly changes/cancels the goal. Do not continue the guarded action while pending.',
       inputSchema: z.object({
-        requestId: z.string().min(24).max(84),
-        waitSeconds: z.number().int().min(1).max(240).optional()
+        requestId: z.string().min(24).max(84).describe('Durable request handle returned by a nofax_request_* tool.'),
+        waitSeconds: z.number().int().min(1).max(240).optional().describe('Maximum seconds to long-poll during this call; defaults to 240. A timeout still returns pending, never approval.')
       }),
+      outputSchema: WAIT_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }
     },
     async (args) => result(await handlers.waitForResponse(args))
@@ -116,7 +166,10 @@ export function buildMcpServer({ handlers = createMcpToolHandlers() } = {}) {
     {
       title: 'Get Nofax request',
       description: 'Recover safe metadata and terminal state for a durable Nofax request. Secret response topics are never returned.',
-      inputSchema: z.object({ requestId: z.string().min(24).max(84) }),
+      inputSchema: z.object({
+        requestId: z.string().min(24).max(84).describe('Durable Nofax request handle to inspect without exposing its secret response topic.')
+      }),
+      outputSchema: GET_REQUEST_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
     async (args) => result(await handlers.getRequest(args))
@@ -127,7 +180,10 @@ export function buildMcpServer({ handlers = createMcpToolHandlers() } = {}) {
     {
       title: 'List pending Nofax requests',
       description: 'List a bounded set of unresolved Nofax request handles for recovery after client or conversation interruption. Secret response topics are never returned.',
-      inputSchema: z.object({ limit: z.number().int().min(1).max(100).optional() }),
+      inputSchema: z.object({
+        limit: z.number().int().min(1).max(100).optional().describe('Maximum number of unresolved requests to return; defaults to 20.')
+      }),
+      outputSchema: LIST_PENDING_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
     async (args) => result(await handlers.listPending(args))

package/src/mcp-tools.mjs

@@ -140,6 +140,17 @@ export function createMcpToolHandlers(overrides = {}) {
     return pendingResult(remote.requestId);
   }
 
+  async function createDurableRemote(kind, input) {
+    let persisted;
+    const remote = await deps.createRemoteRequestImpl({
+      ...input,
+      beforePublish: async (prepared) => {
+        persisted = await persistRemote({ kind, remote: prepared });
+      }
+    });
+    return persisted ?? persistRemote({ kind, remote });
+  }
+
   return {
     async notify({ title = 'Nofax', message }) {
       const current = await config();
@@ -153,7 +164,7 @@ export function createMcpToolHandlers(overrides = {}) {
 
     async requestApproval({ title = 'Nofax approval', message, allowRefine = false }) {
       const current = await config();
-      const remote = await deps.createRemoteRequestImpl({
+      return createDurableRemote('approval', {
         config: current,
         title: validateText(title, 'TITLE', 120),
         message: validateText(message, 'MESSAGE'),
@@ -163,32 +174,29 @@ export function createMcpToolHandlers(overrides = {}) {
         ],
         includeRefine: allowRefine === true
       });
-      return persistRemote({ kind: 'approval', remote });
     },
 
     async requestChoice({ title = 'Nofax choice', message, options }) {
       const current = await config();
       const normalized = validateChoiceOptions(options);
-      const remote = await deps.createRemoteRequestImpl({
+      return createDurableRemote('choice', {
         config: current,
         title: validateText(title, 'TITLE', 120),
         message: validateText(message, 'MESSAGE'),
         options: normalized,
         includeRefine: false
       });
-      return persistRemote({ kind: 'choice', remote });
     },
 
     async requestRefinement({ title = 'Nofax refinement', message }) {
       const current = await config();
-      const remote = await deps.createRemoteRequestImpl({
+      return createDurableRemote('refinement', {
         config: current,
         title: validateText(title, 'TITLE', 120),
         message: validateText(message, 'MESSAGE'),
         options: [],
         includeRefine: true
       });
-      return persistRemote({ kind: 'refinement', remote });
     },
 
     async waitForResponse({ requestId, waitSeconds }) {

package/src/ntfy.mjs

@@ -96,6 +96,7 @@ export async function createRemoteRequest({
   options = [],
   includeRefine = false,
   shortcutName = config.refineShortcutName ?? DEFAULT_REFINE_SHORTCUT,
+  beforePublish = async () => {},
   fetchImpl = fetch
 }) {
   const normalized = normalizeOptions(options);
@@ -126,8 +127,10 @@ export async function createRemoteRequest({
     }
   }
 
+  const remote = { requestId, responseTopic, allowed };
+  await beforePublish(remote);
   await sendNotification({ config, title, message, actions, fetchImpl });
-  return { requestId, responseTopic, allowed };
+  return remote;
 }
 
 function parseNtfyPoll(text, requestId, allowed) {
@@ -149,7 +152,7 @@ function parseNtfyPoll(text, requestId, allowed) {
 export async function pollRemoteResponse({ config, responseTopic, requestId, allowed, fetchImpl = fetch }) {
   let response;
   try {
-    response = await fetchImpl(`${config.server}/${responseTopic}/json?poll=1&since=10m`, {
+    response = await fetchImpl(`${config.server}/${responseTopic}/json?poll=1&since=all`, {
       method: 'GET',
       headers: { accept: 'application/x-ndjson' }
     });