llms-ink 0.7.0 → 0.7.2

package/README.md

@@ -307,7 +307,7 @@ JavaScript uses a 65-second total request deadline; pass `{ signal }` to cancel
 `llms-ink/guard/claude` binds one Claude Agent SDK conversation to one authenticated local Guard session. Install the optional peer separately:
 
 ```sh
-npm install llms-ink@0.7.0 @anthropic-ai/claude-agent-sdk@0.3.319
+npm install llms-ink@0.7.2 @anthropic-ai/claude-agent-sdk@0.3.319
 ```
 
 First [start the Python 0.10.0 local service](https://llms.ink/guard/service/) with a reviewed gateway configuration and existing Claude authentication. Then try the bundled terminal host:
@@ -330,3 +330,16 @@ The default fixed session TTL is 900 seconds (`ttl`, maximum 86400), with no ren
 Allowed results go to Claude using the host's authentication, after local inspection. The adapter does not call hosted Inspect. Other SDK entry points do not import the optional Claude dependency. [Guide](https://llms.ink/guard/claude/) · [Runnable example](examples/guard-claude.mjs).
 
 Lifecycle tests use real service sockets and subprocess effects with a simulated SDK loop. Run them with `LLMS_INK_GUARD_TEST_PYTHON=/absolute/python npm run test:guard` after installing Python `llms-ink==0.10.0`. The separately opted-in `test:guard:live` requires `LLMS_INK_CLAUDE_LIVE=1`, existing Claude authentication and the optional local model when `LLMS_INK_HOST_REAL_MODEL=1`. Scripted fixture approvals are interoperability evidence, not independent human review or proof of attack prevention.
+
+### Guard host diagnostics
+
+`GuardHostError.code` identifies the failed local check or a fixed host-reported result category. `operationCode` preserves the preceding operation when cleanup fails; the primary `code` then describes cleanup. The terminal example prints both. No raw provider error, prompt, tool output, command or credential is copied into these codes.
+
+- `service_status_failed` / `session_inactive`: check the local service with `llms-ink-guard doctor --config FILE --owner-file FILE` (Python 0.12.0). Start a new conversation after resolving it.
+- `guard_connection_failed` / `unexpected_tools` / `session_mismatch` / `host_not_initialized`: the host did not establish the expected guarded conversation. Check host compatibility and configuration; permissions are not broadened.
+- `host_stream_failed` / `host_stream_ended` / `host_startup_failed`: the host failed to start or continue. These codes do not establish a provider, authentication or network cause.
+- `host_result_error` / `host_turn_limit` / `host_budget_limit` / `host_output_retry_limit`: the host reported an error or one of its configured limits. Only known subtype names are mapped; error text is omitted.
+- `message_callback_failed`: the application output callback failed. `turn_timeout`, `session_expired` and `conversation_closed` distinguish adapter deadlines and closure.
+- `revocation_unconfirmed`, `host_cleanup_failed` or `credential_cleanup_failed`: retain the reported private directory and retry `close()` or use owner-controlled revocation. Do not treat cleanup as complete.
+
+A failed running turn closes the conversation and attempts revocation; no automatic retry or unguarded fallback occurs. Successful turns may already have performed approved actions, and an error can occur after a tool effect: these codes are not proof of non-execution. Session IDs and recovery paths remain available only for cleanup failures and should not be posted publicly. `host_error` is the fallback for argument/state errors and externally constructed errors.

package/dist/guard-claude.d.ts

@@ -31,10 +31,15 @@ export interface GuardedClaudeConversation {
     /** Revoke authority and close the host. Idempotent after confirmed cleanup; retry on cleanup errors. */
     close(): Promise<void>;
 }
+/** Local failure categories. No provider text, tool output or credentials are copied into these values. */
+export type GuardHostErrorCode = 'host_error' | 'session_create_failed' | 'host_startup_failed' | 'service_status_failed' | 'session_inactive' | 'host_stream_failed' | 'host_stream_ended' | 'session_mismatch' | 'guard_connection_failed' | 'unexpected_tools' | 'host_not_initialized' | 'message_callback_failed' | 'host_result_error' | 'host_turn_limit' | 'host_budget_limit' | 'host_output_retry_limit' | 'turn_timeout' | 'session_expired' | 'conversation_closed' | 'revocation_unconfirmed' | 'host_cleanup_failed' | 'credential_cleanup_failed';
 export declare class GuardHostError extends Error {
     readonly sessionId: string | undefined;
     readonly credentialDirectory: string | undefined;
-    constructor(message: string, sessionId?: string, credentialDirectory?: string);
+    readonly code: GuardHostErrorCode;
+    /** Original operation failure when cleanup itself failed. Cleanup remains the primary error. */
+    readonly operationCode: GuardHostErrorCode | undefined;
+    constructor(message: string, sessionId?: string, credentialDirectory?: string, code?: GuardHostErrorCode, operationCode?: GuardHostErrorCode);
 }
 /**
  * Create one non-resumable, tool-scoped conversation. New conversations require new instances.

package/dist/guard-claude.js

@@ -8,11 +8,16 @@ import { query } from '@anthropic-ai/claude-agent-sdk';
 export class GuardHostError extends Error {
     sessionId;
     credentialDirectory;
-    constructor(message, sessionId, credentialDirectory) {
+    code;
+    /** Original operation failure when cleanup itself failed. Cleanup remains the primary error. */
+    operationCode;
+    constructor(message, sessionId, credentialDirectory, code = 'host_error', operationCode) {
         super(message);
         this.name = 'GuardHostError';
         this.sessionId = sessionId;
         this.credentialDirectory = credentialDirectory;
+        this.code = code;
+        this.operationCode = operationCode;
     }
 }
 const idPattern = /^[a-f0-9]{32}$/;
@@ -102,7 +107,7 @@ export async function createGuardedClaude(options) {
                     throw new Error();
             }
             catch {
-                throw new GuardHostError('Session revocation could not be confirmed. Keep the credential directory and retry close or revoke it with the owner CLI.', sessionId, directory);
+                throw new GuardHostError('Session revocation could not be confirmed. Keep the credential directory and retry close or revoke it with the owner CLI.', sessionId, directory, 'revocation_unconfirmed');
             }
         }
     }
@@ -125,15 +130,26 @@ export async function createGuardedClaude(options) {
             }
             catch { /* no recoverable credential */ }
         }
-        await revoke();
-        await rm(directory, { recursive: true, force: true });
-        throw new GuardHostError('Could not create a guarded conversation.');
+        try {
+            await revoke();
+            await rm(directory, { recursive: true, force: true });
+        }
+        catch (error) {
+            throw cleanupError(error, 'session_create_failed');
+        }
+        throw new GuardHostError('Could not create a guarded conversation.', undefined, undefined, 'session_create_failed');
     }
     const guardId = sessionId;
     const hostId = randomUUID(), input = new Input(), abort = new AbortController();
     let closing = false, closed = false, busy = false, initialized = false, closeWork;
     let host;
     let expiresTimer;
+    let stopReason;
+    function cleanupError(error, operationCode) {
+        if (error instanceof GuardHostError)
+            return new GuardHostError(error.message, error.sessionId, error.credentialDirectory, error.code, operationCode);
+        return new GuardHostError('Credential cleanup did not complete. Retry cleanup.', sessionId, directory, 'credential_cleanup_failed', operationCode);
+    }
     async function whileOpen(work) {
         if (abort.signal.aborted)
             throw new GuardHostError('Conversation closed.');
@@ -154,6 +170,7 @@ export async function createGuardedClaude(options) {
             return;
         if (closeWork)
             return closeWork;
+        stopReason ??= 'conversation_closed';
         closing = true;
         input.close();
         abort.abort();
@@ -170,11 +187,16 @@ export async function createGuardedClaude(options) {
                 host?.close();
             }
             catch {
-                failure ??= new GuardHostError('Claude host cleanup did not complete. Retry close.', guardId, directory);
+                failure ??= new GuardHostError('Claude host cleanup did not complete. Retry close.', guardId, directory, 'host_cleanup_failed');
             }
             if (failure)
                 throw failure;
-            await rm(directory, { recursive: true, force: true });
+            try {
+                await rm(directory, { recursive: true, force: true });
+            }
+            catch {
+                throw new GuardHostError('Credential cleanup did not complete. Retry close.', guardId, directory, 'credential_cleanup_failed');
+            }
             closed = true;
         })();
         try {
@@ -185,7 +207,7 @@ export async function createGuardedClaude(options) {
         }
     }
     async function elicit(request, context) {
-        if (closing || !busy || context.signal.aborted || request.serverName !== 'guarded' || (request.mode ?? 'form') !== 'form'
+        if (closing || !initialized || !busy || context.signal.aborted || request.serverName !== 'guarded' || (request.mode ?? 'form') !== 'form'
             || typeof request.message !== 'string' || Buffer.byteLength(request.message) > 8192 || !sameShape(request.requestedSchema, reviewSchema))
             return { action: 'decline' };
         const lifetime = new AbortController();
@@ -224,53 +246,79 @@ export async function createGuardedClaude(options) {
         host = query({ prompt: input, options: sdkOptions });
         // Revocation on idle expiry does not wait for another prompt. Failures remain
         // observable through close(); the service independently enforces its TTL.
-        expiresTimer = setTimeout(() => { void close().catch(() => { }); }, ttl * 1000);
+        expiresTimer = setTimeout(() => { stopReason ??= 'session_expired'; void close().catch(() => { }); }, ttl * 1000);
         expiresTimer.unref();
     }
     catch {
-        await close();
-        throw new GuardHostError('Claude host startup failed.');
+        try {
+            await close();
+        }
+        catch (error) {
+            throw cleanupError(error, 'host_startup_failed');
+        }
+        throw new GuardHostError('Claude host startup failed.', undefined, undefined, 'host_startup_failed');
     }
     return Object.freeze({ sessionId: guardId,
         async run(prompt, onMessage) {
             if (closing || busy)
-                throw new GuardHostError('The conversation is closed or another turn is running.');
+                throw new GuardHostError('The conversation is closed or another turn is running.', undefined, undefined, closing ? (stopReason ?? 'conversation_closed') : 'host_error');
             if (typeof prompt !== 'string' || !prompt.trim() || prompt.trimStart().startsWith('/') || Buffer.byteLength(prompt) > 131072)
                 throw new GuardHostError('Provide a text prompt up to 128 KiB; host commands require a new conversation.');
             busy = true;
-            const timer = setTimeout(() => { void close().catch(() => { }); }, timeout);
+            let failureCode = 'service_status_failed';
+            function fail(code) { failureCode = code; throw new Error(); }
+            const timer = setTimeout(() => { stopReason ??= 'turn_timeout'; void close().catch(() => { }); }, timeout);
             try {
                 const state = await control(python, ['service-status', '--owner-file', ownerFile]);
                 if (closing || state.ok !== true || !Array.isArray(state.sessions) || !state.sessions.some(s => s?.sessionId === guardId && s.active === true))
-                    throw new Error();
+                    fail('session_inactive');
+                failureCode = 'host_stream_failed';
                 input.send(prompt, hostId);
                 while (true) {
+                    failureCode = 'host_stream_failed';
                     const next = await whileOpen(host.next());
                     if (next.done || closing)
-                        throw new Error();
+                        fail('host_stream_ended');
                     const message = next.value;
                     if ('session_id' in message && message.session_id !== hostId)
-                        throw new Error();
+                        fail('session_mismatch');
                     if (message.type === 'system' && message.subtype === 'init') {
-                        if (message.mcp_servers.length !== 1 || message.mcp_servers[0].name !== 'guarded' || message.mcp_servers[0].status !== 'connected'
-                            || !message.tools.length || message.tools.some(t => !t.startsWith('mcp__guarded__')))
-                            throw new Error();
+                        if (!Array.isArray(message.mcp_servers) || message.mcp_servers.length !== 1 || message.mcp_servers[0]?.name !== 'guarded' || message.mcp_servers[0]?.status !== 'connected')
+                            fail('guard_connection_failed');
+                        if (!Array.isArray(message.tools) || !message.tools.length || message.tools.some(t => typeof t !== 'string' || !t.startsWith('mcp__guarded__')))
+                            fail('unexpected_tools');
                         initialized = true;
                     }
+                    // Error results can precede initialization. Only fixed subtype names are retained.
+                    if (message.type === 'result' && message.is_error) {
+                        const code = message.subtype === 'error_max_turns' ? 'host_turn_limit' : message.subtype === 'error_max_budget_usd' ? 'host_budget_limit' : message.subtype === 'error_max_structured_output_retries' ? 'host_output_retry_limit' : 'host_result_error';
+                        fail(code);
+                    }
+                    // Claude can emit subscription rate status before its initialization
+                    // announcement. Discard it until the guard connection and tools are
+                    // verified; it grants no authority and never reaches the callback.
+                    if (!initialized && message.type === 'rate_limit_event')
+                        continue;
                     if (!initialized && message.type !== 'system')
-                        throw new Error();
-                    if (onMessage)
+                        fail('host_not_initialized');
+                    if (onMessage) {
+                        failureCode = 'message_callback_failed';
                         await whileOpen(Promise.resolve().then(() => onMessage(message)));
+                    }
                     if (message.type === 'result') {
-                        if (message.is_error)
-                            throw new Error();
                         return message;
                     }
                 }
             }
             catch {
-                await close();
-                throw new GuardHostError('Guarded turn did not complete; the conversation was closed.');
+                const code = stopReason ?? failureCode;
+                try {
+                    await close();
+                }
+                catch (error) {
+                    throw cleanupError(error, code);
+                }
+                throw new GuardHostError(`Guarded turn did not complete (${code}); the conversation was closed.`, undefined, undefined, code);
             }
             finally {
                 clearTimeout(timer);

package/dist/index.d.ts

@@ -15,7 +15,7 @@
  */
 import { type InspectionReceipt } from './inspect.ts';
 export type { InspectionReceipt } from './inspect.ts';
-export declare const VERSION = "0.7.0";
+export declare const VERSION = "0.7.2";
 export declare const DEFAULT_BASE_URL = "https://llms.ink";
 /** `llms` for the index (llms.txt), `full` for llms-full.txt. */
 export type Mode = 'llms' | 'full';

package/dist/index.js

@@ -15,7 +15,7 @@
  */
 import { prepareInspection, inspectionJson, inspectionReceipt } from "./inspect.js";
 import { env } from "./env.js";
-export const VERSION = '0.7.0';
+export const VERSION = '0.7.2';
 export const DEFAULT_BASE_URL = 'https://llms.ink';
 /**
  * An API error, or llms.ink couldn't be reached (then `status` and `code` are undefined).

package/examples/guard-claude.mjs

@@ -2,7 +2,7 @@
 // Run from an installed llms-ink package with the optional Claude SDK peer installed.
 import {parseArgs} from 'node:util';
 import {createInterface} from 'node:readline/promises';
-import {createGuardedClaude} from '../dist/guard-claude.js';
+import {createGuardedClaude,GuardHostError} from '../dist/guard-claude.js';
 const {values}=parseArgs({options:{'owner-file':{type:'string'},python:{type:'string'},cwd:{type:'string'},model:{type:'string'},'claude-executable':{type:'string'}}});
 if(!process.stdin.isTTY || !process.stdout.isTTY) throw Error('This example requires an interactive terminal for each approval.');
 if(!values['owner-file'] || !values.python || !values.cwd) throw Error('Pass --owner-file, --python and --cwd with absolute paths.');
@@ -10,6 +10,15 @@ const terminal=createInterface({input:process.stdin,output:process.stdout});
 // Preserve complete text while making terminal controls and bidi controls visible.
 const plain=text=>text.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g,c=>'\\u'+c.charCodeAt(0).toString(16).padStart(4,'0'));
 let conversation,stopping=false;
+const report=error=>{
+ console.error(error instanceof GuardHostError?error.message:'The terminal conversation did not complete.');
+ if(error instanceof GuardHostError){
+  console.error('Failure code:',error.code);
+  if(error.operationCode)console.error('Original operation:',error.operationCode);
+  if(error.sessionId)console.error('Session ID:',error.sessionId);
+  if(error.credentialDirectory)console.error('Credential directory:',error.credentialDirectory);
+ }
+};
 const stop=()=>{stopping=true;terminal.close();void conversation?.close().catch(()=>{});};
 terminal.on('SIGINT',stop);terminal.on('close',()=>{stopping=true;void conversation?.close().catch(()=>{});});process.on('SIGTERM',stop);
 try{
@@ -27,8 +36,8 @@ try{
    if(message.type==='assistant')for(const part of message.message.content)if(part.type==='text')process.stdout.write(plain(part.text)+'\n');
   });
  }
-}catch(error){if(!stopping){console.error(error.message);process.exitCode=1;}}
+}catch(error){if(!stopping){report(error);process.exitCode=1;}}
 finally{
  terminal.close();process.removeListener('SIGTERM',stop);
- try{await conversation?.close();}catch(error){console.error(error.message);if(error.sessionId)console.error('Session ID:',error.sessionId);if(error.credentialDirectory)console.error('Credential directory:',error.credentialDirectory);process.exitCode=1;}
+ try{await conversation?.close();}catch(error){report(error);process.exitCode=1;}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llms-ink",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Turn any link — site, docs section, page, GitHub repo, PDF or video — into llms.txt and llms-full.txt. Typed client for llms.ink, plus a Vite plugin, an Astro integration and middleware that serve the files from your site, and Vercel AI SDK tools. No dependencies.",
   "type": "module",
   "exports": {