llms-ink 0.7.2 → 0.8.1

package/README.md

@@ -307,10 +307,10 @@ 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.2 @anthropic-ai/claude-agent-sdk@0.3.319
+npm install llms-ink@0.8.1 @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:
+First [start the Python 0.14.0 local service](https://llms.ink/guard/service/) with a reviewed gateway configuration and existing Claude authentication. Then try the bundled terminal host:
 
 ```sh
 node node_modules/llms-ink/examples/guard-claude.mjs \
@@ -325,11 +325,11 @@ For application hosts, import `createGuardedClaude` and pass absolute `ownerFile
 
 The default fixed session TTL is 900 seconds (`ttl`, maximum 86400), with no renewal. Each turn has a 120000 ms deadline (`turnTimeoutMs`, maximum 600000). Reviews stop after 55 seconds. The adapter configures no native tools, other MCP connections, plugins or local hooks. SDK `maxTurns` defaults to 12 and `maxBudgetUsd` to 1; SDK cost estimates are not a hard billing limit. Optional `model` and `claudeExecutable` select the host model/binary.
 
-`GuardHostError` reports incomplete cleanup with `sessionId` and `credentialDirectory`. If revocation cannot be confirmed, the private credential file remains for recovery; retry `close()` or revoke through the owner CLI. A host process killed without cleanup can leave authority until the service's TTL. The owner process, SDK and approval UI are trusted; private files do not isolate malicious same-user code. This is not a process sandbox, exposure ledger or automatic desktop plugin. Compaction does not establish clean context.
+`GuardHostError` reports incomplete cleanup with `sessionId` and `credentialDirectory`. If revocation cannot be confirmed, the private credential file remains for recovery; retry `close()` or revoke through the owner CLI. The adapter creates a host-bound session and keeps a separate owner watcher connected through an idle pipe. The service refuses attachment before that binding and revokes on observed watcher disconnection; killing the host closes its pipe and ends the watcher. A stopped watcher or inherited open pipe can delay observation until fixed expiry. No heartbeat, renewal, resume or crash-proof guarantee is added. The owner process, SDK and approval UI are trusted; private files do not isolate malicious same-user code. This is not a process sandbox, exposure ledger or automatic desktop plugin. Compaction does not establish clean context.
 
 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.
+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.14.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
 
@@ -337,9 +337,10 @@ Lifecycle tests use real service sockets and subprocess effects with a simulated
 
 - `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_watch_failed`: the owner lifetime channel failed or ended. The conversation closes; start a new one after checking the local service. This code alone does not distinguish watcher failure from external revocation.
 - `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.
+- `revocation_unconfirmed`, `host_cleanup_failed`, `host_watch_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

@@ -8,7 +8,7 @@ export interface GuardReview {
 export interface GuardedClaudeOptions {
     /** Private owner credential. This path is used by the control process, never sent to Claude. */
     ownerFile: string;
-    /** Absolute Python interpreter with llms-ink[guard] 0.10.0 installed. */
+    /** Absolute Python interpreter with llms-ink[guard] 0.14.0+ installed. */
     python: string;
     /** Called for each fresh approval. Only literal true accepts. Errors, cancellation and timeout decline. */
     review: (request: GuardReview) => Promise<boolean>;
@@ -32,7 +32,7 @@ export interface GuardedClaudeConversation {
     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 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' | 'host_watch_failed' | 'host_watch_cleanup_failed';
 export declare class GuardHostError extends Error {
     readonly sessionId: string | undefined;
     readonly credentialDirectory: string | undefined;
@@ -44,6 +44,7 @@ export declare class GuardHostError extends Error {
 /**
  * Create one non-resumable, tool-scoped conversation. New conversations require new instances.
  * The owner process, SDK and review callback are trusted. This is not an OS sandbox.
- * A process crash leaves authority bounded by the fixed TTL; there is no crash-proof lease or exposure ledger.
+ * A private owner watcher revokes authority on observed host disconnect, with a fixed TTL backstop.
+ * A stopped host/watcher can retain its socket until TTL; this is not an exposure ledger or a sandbox.
  */
 export declare function createGuardedClaude(options: GuardedClaudeOptions): Promise<GuardedClaudeConversation>;

package/dist/guard-claude.js

@@ -1,5 +1,5 @@
 /** Node/POSIX host integration for explicitly scoped Claude Agent SDK conversations. */
-import { execFile } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { mkdtemp, chmod, lstat, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
@@ -47,6 +47,69 @@ function control(python, args) {
         }
     }));
 }
+async function watchHost(python, ownerFile, sessionId, lost) {
+    const child = spawn(python, ['-m', 'llms_ink.guard', 'session-watch', '--owner-file', ownerFile, '--session-id', sessionId], { stdio: ['pipe', 'pipe', 'ignore'] });
+    let expected = false, finished = false, acknowledged = false, data = '';
+    let accept = () => { }, reject = () => { };
+    const ready = new Promise((resolve, fail) => { accept = resolve; reject = () => fail(new GuardHostError('Host lifetime binding failed.', undefined, undefined, 'host_watch_failed')); });
+    const failure = () => { reject(); if (!expected)
+        lost(); };
+    const ended = new Promise(resolve => child.once('close', () => { finished = true; failure(); resolve(); }));
+    child.once('error', failure);
+    child.stdin.on('error', failure);
+    child.stdout.once('end', () => { if (!expected)
+        failure(); });
+    child.stdout.on('data', (chunk) => {
+        if (acknowledged || chunk.length + Buffer.byteLength(data) > 16384) {
+            failure();
+            return;
+        }
+        data += chunk.toString('utf8');
+        if (!data.includes('\n'))
+            return;
+        try {
+            const value = JSON.parse(data);
+            if (!sameShape(value, { ok: true, sessionId }))
+                throw new Error();
+            acknowledged = true;
+            data = '';
+            accept();
+        }
+        catch {
+            failure();
+        }
+    });
+    async function waitForExit(ms) {
+        let timer;
+        try {
+            return await Promise.race([ended.then(() => true), new Promise(resolve => { timer = setTimeout(() => resolve(false), ms); })]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    const watcher = { async stop() {
+            expected = true;
+            child.stdin.destroy();
+            if (finished || await waitForExit(5000))
+                return;
+            child.kill('SIGKILL');
+            if (!await waitForExit(2000))
+                throw new GuardHostError('Host watcher cleanup did not complete.', undefined, undefined, 'host_watch_cleanup_failed');
+        } };
+    const timer = setTimeout(failure, 30000);
+    try {
+        await ready;
+        return watcher;
+    }
+    catch (error) {
+        await watcher.stop();
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 class Input {
     pending;
     wake;
@@ -75,7 +138,8 @@ class Input {
 /**
  * Create one non-resumable, tool-scoped conversation. New conversations require new instances.
  * The owner process, SDK and review callback are trusted. This is not an OS sandbox.
- * A process crash leaves authority bounded by the fixed TTL; there is no crash-proof lease or exposure ledger.
+ * A private owner watcher revokes authority on observed host disconnect, with a fixed TTL backstop.
+ * A stopped host/watcher can retain its socket until TTL; this is not an exposure ledger or a sandbox.
  */
 export async function createGuardedClaude(options) {
     options = { ...options };
@@ -91,6 +155,7 @@ export async function createGuardedClaude(options) {
     const directory = await mkdtemp(join(tmpdir(), 'ink-host-'));
     await chmod(directory, 0o700);
     const file = join(directory, 'session.json');
+    const issueStarted = performance.now();
     let sessionId;
     async function revoke() {
         if (!sessionId)
@@ -112,7 +177,7 @@ export async function createGuardedClaude(options) {
         }
     }
     try {
-        const result = await control(python, ['session-create', '--owner-file', ownerFile, '--output', file, '--ttl', String(ttl)]);
+        const result = await control(python, ['session-create', '--owner-file', ownerFile, '--output', file, '--ttl', String(ttl), '--host-bound']);
         if (typeof result.sessionId !== 'string' || !idPattern.test(result.sessionId))
             throw new Error();
         sessionId = result.sessionId;
@@ -143,6 +208,7 @@ export async function createGuardedClaude(options) {
     const hostId = randomUUID(), input = new Input(), abort = new AbortController();
     let closing = false, closed = false, busy = false, initialized = false, closeWork;
     let host;
+    let watcher;
     let expiresTimer;
     let stopReason;
     function cleanupError(error, operationCode) {
@@ -189,6 +255,12 @@ export async function createGuardedClaude(options) {
             catch {
                 failure ??= new GuardHostError('Claude host cleanup did not complete. Retry close.', guardId, directory, 'host_cleanup_failed');
             }
+            try {
+                await watcher?.stop();
+            }
+            catch {
+                failure ??= new GuardHostError('Host watcher cleanup did not complete. Retry close.', guardId, directory, 'host_watch_cleanup_failed');
+            }
             if (failure)
                 throw failure;
             try {
@@ -233,6 +305,15 @@ export async function createGuardedClaude(options) {
         }
     }
     try {
+        watcher = await watchHost(python, ownerFile, guardId, () => {
+            if (!closing) {
+                stopReason = performance.now() - issueStarted >= ttl * 1000 ? 'session_expired' : 'host_watch_failed';
+                if (watcher)
+                    void close().catch(() => { });
+            }
+        });
+        if (closing || stopReason)
+            throw new Error();
         const sdkOptions = {
             abortController: abort, sessionId: hostId, persistSession: false, settingSources: [], plugins: [], tools: [],
             strictMcpConfig: true, mcpServers: { guarded: { command: python, args: ['-m', 'llms_ink.guard', 'connect', '--session-file', file] } },
@@ -246,22 +327,33 @@ 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(() => { stopReason ??= 'session_expired'; void close().catch(() => { }); }, ttl * 1000);
+        expiresTimer = setTimeout(() => { stopReason ??= 'session_expired'; void close().catch(() => { }); }, Math.max(0, ttl * 1000 - (performance.now() - issueStarted)));
         expiresTimer.unref();
     }
     catch {
+        const code = stopReason ?? (watcher ? 'host_startup_failed' : 'host_watch_failed');
         try {
             await close();
         }
         catch (error) {
-            throw cleanupError(error, 'host_startup_failed');
+            throw cleanupError(error, code);
         }
-        throw new GuardHostError('Claude host startup failed.', undefined, undefined, 'host_startup_failed');
+        throw new GuardHostError('Claude host startup failed.', undefined, undefined, code);
     }
     return Object.freeze({ sessionId: guardId,
         async run(prompt, onMessage) {
-            if (closing || busy)
-                throw new GuardHostError('The conversation is closed or another turn is running.', undefined, undefined, closing ? (stopReason ?? 'conversation_closed') : 'host_error');
+            if (closing) {
+                const code = stopReason ?? 'conversation_closed';
+                try {
+                    await close();
+                }
+                catch (error) {
+                    throw cleanupError(error, code);
+                }
+                throw new GuardHostError('The conversation is closed.', undefined, undefined, code);
+            }
+            if (busy)
+                throw new GuardHostError('Another turn is running.');
             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;

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.2";
+export declare const VERSION = "0.8.1";
 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.2';
+export const VERSION = '0.8.1';
 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "llms-ink",
-  "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.",
+  "version": "0.8.1",
+  "description": "Turn any link \u2014 site, docs section, page, GitHub repo, PDF or video \u2014 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": {
     ".": {