nofax 0.2.2 → 0.2.4

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.2",
+  "version": "0.2.4",
   "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.2' },
+    { name: 'nofax', version: '0.2.4' },
     { 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/requests.mjs

@@ -103,11 +103,10 @@ export async function savePendingRequest({ home, env, request }) {
 
 export async function loadRequest({ home, env, requestId }) {
   const { file, terminal } = paths({ home, env, requestId });
+  const claimed = await loadTerminalClaim(terminal);
+  if (claimed !== null) return claimed;
   try {
-    const current = validateRequest(JSON.parse(await readFile(file, 'utf8')));
-    if (current.status === 'resolved') return current;
-    const claimed = await loadTerminalClaim(terminal);
-    return claimed ?? current;
+    return validateRequest(JSON.parse(await readFile(file, 'utf8')));
   } catch (error) {
     if (error?.code === 'ENOENT') throw new Error('NOFAX_REQUEST_NOT_FOUND');
     if (error instanceof SyntaxError) throw new Error('NOFAX_REQUEST_INVALID_JSON');
@@ -126,11 +125,10 @@ export async function resolveRequest({ home, env, requestId, response, resolvedA
     decision: response.decision,
     ...(response.text === undefined ? {} : { text: response.text })
   });
-  const { file, terminal } = paths({ home, env, requestId });
+  const { terminal } = paths({ home, env, requestId });
   if (!await claimTerminal(terminal, resolved)) {
     return loadRequest({ home, env, requestId });
   }
-  await atomicWrite(file, resolved);
   return resolved;
 }