@tealbrick/avm 0.2.6 → 0.2.7

package/ROUTINES.md

@@ -1,4 +1,4 @@
-# Shared host routines (Eve 0.58.1)
+# Shared host routines (Eve 0.66.0)
 
 The AVM package owns the host store, typed client and opt-in Eve routine tool.
 The host store is authoritative. Neither the desktop nor Eve edits a second
@@ -83,3 +83,17 @@ remove the corresponding old static schedule from discovery, then build/restart
 once. Never leave both static and dynamic execution enabled for the same job.
 Subsequent edits need no rebuild or restart. Desktop reads dynamic rows from
 management discovery and hides the dispatcher implementation from its list.
+
+## Deployment recovery and standing delegation (0.2.7)
+
+Use `startRoutineRecovery` from `@tealbrick/avm/routines-recovery` in the host
+service. It reconciles at startup and on a bounded timer without guest calls.
+Keep its stop handle for shutdown. `reconcile` is an internal host-store action;
+the example HTTP bridge does not expose it to the guest.
+
+Optional `delegation()` is re-read for native app-auth CRUD calls. It binds the
+exact scope, expiry, allowed operations, name prefix and wake permission.
+`authorizeExecution()` independently gates each claim batch. The supplied host
+service requires an external execution grant and fails closed without one.
+`misfireGraceMs` controls the explicit late-start window. No backlog burst or
+uncertain side-effect retry is added. See the root DEPLOYMENT-FIXES.md contract.

package/bin/routine-host.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// Run only on the AVMM host. Bind its worker bridge IP, not a public interface.
+import {createServer} from 'node:http';
+import {execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+import {timingSafeEqual} from 'node:crypto';
+import {readFileSync,lstatSync} from 'node:fs';
+import {startRoutineRecovery} from '@tealbrick/avm/routines-recovery';
+import {createRoutineStore} from '@tealbrick/avm/routines';
+import {createAvmmWakeAdapter} from '@tealbrick/avm/wake';
+const configPath=process.env.TEAL_WAKE_CONFIG;if(!configPath)throw Error('routine_host_config_required');
+const configStat=lstatSync(configPath);if(!configStat.isFile()||configStat.isSymbolicLink()||(configStat.mode&0o077))throw Error('routine_host_config_permissions');
+const config=JSON.parse(readFileSync(process.env.TEAL_WAKE_CONFIG,'utf8'));
+if(typeof config.token!=='string'||config.token.length<32||!config.routineScope||!config.routineStore||!config.executionGrantFile)throw Error('routine_host_enrollment_required');
+const run=promisify(execFile);
+const adapter=createAvmmWakeAdapter({allowed:true,timezone:'UTC',credentialsRefreshOnRequest:config.credentialsRefreshOnRequest===true,worker:config.worker,ownerKey:config.ownerKey,transport:{async run(argv,{signal}={}){try{const r=await run('/usr/local/bin/avm',argv,{signal,maxBuffer:1048576});return {exitCode:0,...r};}catch{return {exitCode:1,stdout:'',stderr:''};}}}});
+const routines=config.routineScope?createRoutineStore({path:config.routineStore,scope:config.routineScope,misfireGraceMs:config.misfireGraceMs,wake:adapter,delegation:async()=>{try{return JSON.parse(readFileSync(config.delegationFile,'utf8'));}catch{return null;}},authorizeExecution:async()=>{try{const grant=JSON.parse(readFileSync(config.executionGrantFile,'utf8'));return grant.enabled===true&&grant.expiresAt>Date.now()&&Object.entries(config.routineScope).every(([key,value])=>grant.scope?.[key]===value);}catch{return false;}}}):null;
+const recovery=routines?startRoutineRecovery(routines,{onError:()=>console.error('routine_wake_reconciliation_pending')}):null;
+process.once('SIGTERM',()=>{recovery?.stop();server.close();});
+const server=createServer(async(req,res)=>{
+ const expected=Buffer.from(`Bearer ${config.token}`), supplied=Buffer.from(req.headers.authorization??'');
+ if(req.socket.remoteAddress!==config.workerIp||supplied.length!==expected.length||!timingSafeEqual(supplied,expected)){res.writeHead(403).end();return;}
+ try{
+  let result;
+  if(req.method==='GET'&&req.url==='/status') result=await adapter.status();
+  else if(req.method==='POST'&&req.url==='/routines'&&routines){
+   let body='';for await(const chunk of req){body+=chunk;if(body.length>20000)throw Error('too_large');}
+   const {action,input}=JSON.parse(body);if(!['status','apply','claim','accepted','complete','failed','delegated-status','delegated-apply'].includes(action))throw Error('unsupported_operation');result=await routines.call(action,input);
+  }
+  else if(req.method==='POST'&&req.url==='/reconcile'){
+   if(routines)throw Error('shared_registry_owns_wake');
+   let body='';for await(const chunk of req){body+=chunk;if(body.length>20000)throw Error('too_large');}
+   const routines=JSON.parse(body);
+   if(!Array.isArray(routines)||routines.length>50||routines.some(r=>!r||typeof r.name!=='string'||!/^[a-z0-9][a-z0-9-]{0,47}$/.test(r.name)||typeof r.cron!=='string'))throw Error('invalid_routines');
+   await adapter.reconcile(routines);result={ok:true};
+  }else{res.writeHead(404).end();return;}
+  res.writeHead(200,{'content-type':'application/json'}).end(JSON.stringify(result));
+ }catch(error){const allowed=['revision_conflict','schedule_exists','schedule_not_found','wake_unavailable','unsupported_wake_cron','request_id_conflict'];res.writeHead(409,{'content-type':'application/json'}).end(JSON.stringify({ok:false,error:allowed.includes(error?.message)?error.message:'host_operation_failed'}));}
+}).listen(config.port,config.bindIp);

package/dist/client/routines-eve.js

@@ -6,14 +6,15 @@ const input = z.object({ operation: z.enum(['list', 'create', 'update', 'pause',
 export function routineTool(options) {
     return defineTool({ description: 'Manage your host-persisted routines shared with desktop. List first to get current revisions. Create needs a unique lowercase hyphenated name, five-field UTC cron and instruction. Update/pause/resume/remove require the revision returned by list. Wake is optional and off by default. Runs deliver into the owner’s desktop chat. requestId must be a stable UUID for each intended change; reuse it only for an identical retry. Do not claim execution from a saved routine.', inputSchema: input, async execute(args, ctx) {
             const auth = ctx.session.auth.current;
-            if (auth?.authenticator !== 'tealbrick' || auth.principalType !== 'user' || auth.principalId !== options.scope.owner || auth.attributes.org !== options.scope.org || auth.attributes.agentGrantLevel !== 'manage')
+            const delegated = auth?.authenticator === 'app' && auth.principalType === 'runtime' && auth.principalId === 'eve:app';
+            if (!delegated && (auth?.authenticator !== 'tealbrick' || auth.principalType !== 'user' || auth.principalId !== options.scope.owner || auth.attributes.org !== options.scope.org || auth.attributes.agentGrantLevel !== 'manage'))
                 throw Error('routine_manage_permission_required');
             if (args.operation === 'list')
-                return options.bridge.call('status');
+                return options.bridge.call(delegated ? 'delegated-status' : 'status');
             if (!args.requestId)
                 throw Error('request_id_required');
             const { operation, ...fields } = args;
-            return options.bridge.call('apply', { ...fields, operation: operation === 'create' ? 'upsert' : operation === 'remove' ? 'delete' : 'update', ...(operation === 'pause' ? { enabled: false } : operation === 'resume' ? { enabled: true } : {}) });
+            return options.bridge.call(delegated ? 'delegated-apply' : 'apply', { ...fields, operation: operation === 'create' ? 'upsert' : operation === 'remove' ? 'delete' : 'update', ...(operation === 'pause' ? { enabled: false } : operation === 'resume' ? { enabled: true } : {}) });
         } });
 }
 /** Install once; all recurrence definitions are read from the host at execution time. */

package/dist/client/routines-recovery.d.ts

@@ -0,0 +1,9 @@
+import type { RoutineBridge } from './routines.js';
+/** Host lifecycle worker: recovery never depends on a running guest. */
+export declare function startRoutineRecovery(bridge: RoutineBridge, options?: {
+    intervalMs?: number;
+    onError?: (error: unknown) => void;
+}): {
+    ready: Promise<void>;
+    stop(): void;
+};

package/dist/client/routines-recovery.js

@@ -0,0 +1,23 @@
+/** Host lifecycle worker: recovery never depends on a running guest. */
+export function startRoutineRecovery(bridge, options = {}) {
+    const interval = options.intervalMs ?? 15000;
+    if (!Number.isInteger(interval) || interval < 10 || interval > 300000)
+        throw Error('invalid_recovery_interval');
+    let stopped = false;
+    let timer;
+    const tick = async () => {
+        try {
+            await bridge.call('reconcile');
+        }
+        catch (error) {
+            options.onError?.(error);
+        }
+        if (!stopped) {
+            timer = setTimeout(tick, interval);
+            timer.unref();
+        }
+    };
+    const ready = tick();
+    return { ready, stop() { stopped = true; if (timer)
+            clearTimeout(timer); } };
+}

package/dist/client/routines.d.ts

@@ -31,6 +31,13 @@ export interface RoutineSnapshot {
     wake: Record<string, unknown>;
     dynamic: true;
 }
+export interface RoutineDelegation {
+    scope: RoutineScope;
+    expiresAt: number;
+    operations: string[];
+    namePrefix: string;
+    allowWake: boolean;
+}
 export interface RoutineBridge {
     call(action: string, input?: Record<string, unknown>): Promise<any>;
 }
@@ -40,6 +47,9 @@ export declare function createRoutineStore(options: {
     path: string;
     scope: RoutineScope;
     now?: () => number;
+    misfireGraceMs?: number;
+    delegation?: () => Promise<RoutineDelegation | null>;
+    authorizeExecution?: () => Promise<boolean>;
     wake?: {
         status(): Promise<any>;
         validate(rows: {

package/dist/client/routines.js

@@ -26,6 +26,9 @@ export function createRoutineStore(options) {
         throw Error('scope_mismatch');
     const save = (s) => db.prepare('UPDATE state SET json=? WHERE id=1').run(JSON.stringify(s));
     const now = options.now ?? Date.now;
+    const grace = options.misfireGraceMs ?? 120000;
+    if (!Number.isInteger(grace) || grace < 0 || grace > 86400000)
+        throw Error('invalid_misfire_grace');
     const tx = (fn) => { db.exec('BEGIN IMMEDIATE'); try {
         const value = fn();
         db.exec('COMMIT');
@@ -39,18 +42,44 @@ export function createRoutineStore(options) {
     const writeRun = (r) => db.prepare('INSERT OR REPLACE INTO runs VALUES (?,?)').run(r.id, JSON.stringify(r));
     const reconcile = async () => { const s = read(); if (!s.dirty)
         return; if (!options.wake)
-        throw Error('wake_unavailable'); await options.wake.reconcile(s.routines.filter(r => !r.deleted && r.enabled && r.wake)); tx(() => { const current = read(); current.dirty = false; save(current); }); };
+        throw Error('wake_unavailable'); await options.wake.reconcile(s.routines.filter(r => !r.deleted && r.enabled && r.wake)); tx(() => { const current = read(); current.dirty = JSON.stringify(current.routines) !== JSON.stringify(s.routines); save(current); }); };
     let queue = Promise.resolve();
     const call = async (action, input = {}) => {
+        if (action === 'reconcile') {
+            await reconcile();
+            return { ok: true, pending: read().dirty };
+        }
+        if (action === 'delegated-status' || action === 'delegated-apply') {
+            const grant = await options.delegation?.();
+            const operation = action === 'delegated-status' ? 'list' : String(input.operation);
+            if (!grant || !Object.entries(options.scope).every(([key, value]) => grant.scope?.[key] === value) || !Number.isFinite(grant.expiresAt) || grant.expiresAt <= now() || !grant.namePrefix || !grant.operations.includes(operation))
+                throw Error('routine_delegation_required');
+            if (action === 'delegated-apply') {
+                if (typeof input.name !== 'string' || !input.name.startsWith(grant.namePrefix))
+                    throw Error('routine_delegation_scope');
+                const existing = read().routines.find(r => r.name === input.name);
+                if (!grant.allowWake && (input.wake === true || existing?.wake))
+                    throw Error('routine_delegation_wake_denied');
+            }
+            if (action === 'delegated-status') {
+                const result = await call('status');
+                return { ...result, routines: result.routines.filter((r) => r.name.startsWith(grant.namePrefix)), runs: result.runs.filter((r) => r.name.startsWith(grant.namePrefix)) };
+            }
+            action = 'apply';
+        }
         if (action === 'status')
-            return { scope: options.scope, dynamic: true, routines: read().routines.filter(r => !r.deleted), runs: runs(), wake: { ...(await options.wake?.status() ?? { supported: false }), pending: read().dirty, managed: read().routines.filter(r => !r.deleted).map(r => r.name), routines: read().routines.filter(r => !r.deleted && r.wake).map(r => r.name) } };
+            return { executionGranted: options.authorizeExecution ? await options.authorizeExecution() : null, scope: options.scope, dynamic: true, routines: read().routines.filter(r => !r.deleted), runs: runs(), wake: { ...(await options.wake?.status() ?? { supported: false }), pending: read().dirty, managed: read().routines.filter(r => !r.deleted).map(r => r.name), routines: read().routines.filter(r => !r.deleted && r.wake).map(r => r.name) } };
         if (action === 'apply') {
             const patch = change.parse(input), digest = createHash('sha256').update(JSON.stringify(patch)).digest('hex');
             const old = db.prepare('SELECT digest,json FROM receipts WHERE id=?').get(patch.requestId);
             if (old) {
                 if (old.digest !== digest)
                     throw Error('request_id_conflict');
-                return JSON.parse(old.json);
+                try {
+                    await reconcile();
+                }
+                catch { /* Report current persisted state on retries. */ }
+                return { ...JSON.parse(old.json), wakePending: read().dirty };
             }
             const before = read(), prior = before.routines.find(r => r.name === patch.name);
             if (patch.operation === 'upsert' && prior && !prior.deleted)
@@ -80,6 +109,8 @@ export function createRoutineStore(options) {
             return { ok: true, dynamic: true, saved: true, routine: row };
         }
         if (action === 'claim') {
+            if (options.authorizeExecution && !await options.authorizeExecution())
+                return { jobs: [], blocked: 'routine_execution_not_granted' };
             try {
                 await reconcile();
             }
@@ -100,7 +131,7 @@ export function createRoutineStore(options) {
                     const due = row.nextRunAt;
                     row.nextRunAt = nextRoutineTime(row.cron, at);
                     const id = createHash('sha256').update(JSON.stringify([s.scope, row.name, row.revision, due])).digest('hex');
-                    const run = { id, name: row.name, revision: row.revision, dueAt: due, status: at - due > 120000 ? 'missed' : 'claimed', updatedAt: at };
+                    const run = { id, name: row.name, revision: row.revision, dueAt: due, status: at - due > grace ? 'missed' : 'claimed', updatedAt: at };
                     if (!db.prepare('SELECT id FROM runs WHERE id=?').get(id)) {
                         writeRun(run);
                         if (run.status === 'claimed')

package/dist/client/wake.d.ts

@@ -21,10 +21,12 @@ export declare function createAvmmWakeAdapter(options: {
     status(): Promise<{
         supported: boolean;
         reason: string;
+        wakeRequired?: undefined;
         provider?: undefined;
         timezone?: undefined;
     } | {
         supported: boolean;
+        wakeRequired: boolean;
         provider: string;
         timezone: string;
         reason: string;

package/dist/client/wake.js

@@ -58,13 +58,13 @@ export function createAvmmWakeAdapter(options) {
                 if (!Array.isArray(rows))
                     throw Error();
                 const worker = await run(['worker', 'status', options.worker]);
-                if (worker.mode !== 'durable' || !Number.isFinite(worker.idle_timeout_seconds) || worker.idle_timeout_seconds <= lead)
+                if (worker.mode !== 'durable' || !Number.isFinite(worker.idle_timeout_seconds) || (worker.idle_timeout_seconds !== 0 && worker.idle_timeout_seconds <= lead))
                     throw Error();
                 if (worker.auth?.codex === 'shared' && (!options.credentialsRefreshOnRequest || !worker.capabilities?.includes('model:codex-subscription')))
                     throw Error();
                 if (!Array.isArray(worker.capabilities) || !worker.capabilities.includes(`harness:${options.harness ?? 'eve'}`))
                     throw Error();
-                return { supported: true, provider: 'avmm', timezone: 'UTC', reason: 'Minute/hour intervals, daily, weekdays and weekly routines. Host wakes only; Eve executes.' };
+                return { supported: true, wakeRequired: worker.idle_timeout_seconds !== 0, provider: 'avmm', timezone: 'UTC', reason: 'Minute/hour intervals, daily, weekdays and weekly routines. Host wakes only; Eve executes.' };
             }
             catch {
                 return { supported: false, reason: 'Host scheduler, worker capability or idle timeout could not be verified.' };
@@ -80,7 +80,7 @@ export function createAvmmWakeAdapter(options) {
             const existing = await run(['schedule', 'ls']);
             const worker = await run(['worker', 'status', options.worker]);
             const authCaps = worker.auth?.codex === 'shared' ? ['--cap', 'model:codex-subscription'] : [];
-            for (const routine of routines) {
+            for (const routine of worker.idle_timeout_seconds === 0 ? [] : routines) {
                 const key = createHash('sha256').update(routine.name).digest('hex').slice(0, 16);
                 const plans = planWake(routine.cron, Date.now(), lead);
                 for (const [i, p] of plans.entries()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tealbrick/avm",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Typed host-owned AgentVM transport and opt-in Eve capabilities",
   "type": "module",
   "license": "MIT",
@@ -9,7 +9,8 @@
     "README.md",
     "PROVENANCE.md",
     "LICENSE",
-    "ROUTINES.md"
+    "ROUTINES.md",
+    "bin"
   ],
   "engines": {
     "node": ">=24"
@@ -46,6 +47,10 @@
     "./routines-eve": {
       "types": "./dist/client/routines-eve.d.ts",
       "import": "./dist/client/routines-eve.js"
+    },
+    "./routines-recovery": {
+      "types": "./dist/client/routines-recovery.d.ts",
+      "import": "./dist/client/routines-recovery.js"
     }
   },
   "eve": {
@@ -79,5 +84,8 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
+  },
+  "bin": {
+    "tealbrick-routine-host": "bin/routine-host.mjs"
   }
 }