@undefineds.co/xpod 0.4.17 → 0.4.19

package/dist/api/matrix/types.d.ts

@@ -24,6 +24,8 @@ export interface MatrixEventRecord {
     senderWebId?: string;
     originServerTs: number;
     depth?: number;
+    role?: string;
+    resourceId?: string;
     txnId?: string;
     content: Record<string, unknown>;
     stateKey?: string;
@@ -51,6 +53,17 @@ export interface MatrixSendEventRequest {
 export interface MatrixSyncResponse {
     next_batch: string;
     rooms: {
+        invite?: Record<string, {
+            invite_state: {
+                events: MatrixClientEvent[];
+            };
+        }>;
+        leave?: Record<string, {
+            timeline: {
+                events: MatrixClientEvent[];
+                limited: boolean;
+            };
+        }>;
         join: Record<string, {
             state: {
                 events: MatrixClientEvent[];
@@ -95,6 +108,8 @@ export interface MatrixStore {
     sync(context: MatrixStoreContext, options?: {
         since?: string;
         limit?: number;
+        timeout?: number;
+        signal?: AbortSignal;
     }): Promise<MatrixSyncResponse>;
     listJoinedRooms(context: MatrixStoreContext): Promise<string[]>;
     getMembers(roomId: string, context: MatrixStoreContext): Promise<MatrixClientEvent[]>;

package/dist/api/reconciler/AgentWakeRuntimeService.d.ts

@@ -0,0 +1,66 @@
+import type { MatrixStoreContext } from '../matrix/types';
+import type { SharedWakeAgentJob } from './coordination';
+import type { WakeAgentQueue } from './WakeAgentQueue';
+export interface AgentWakeRequest {
+    roomId: string;
+    agent: string;
+    runtimeId: string;
+    leaseMs?: number;
+}
+export interface AgentWakeLeaseRequest extends AgentWakeRequest {
+    id: string;
+    fencingToken: string;
+}
+export interface AgentWakeResult {
+    body: string;
+    handoffTo?: string;
+    evidence?: string[];
+}
+export interface AgentWakeRuntimeBackend {
+    authorize(roomId: string, agent: string, context: MatrixStoreContext): Promise<{
+        thread: string;
+    }>;
+    recover(roomId: string, context: MatrixStoreContext): Promise<void>;
+    loadInput(roomId: string, job: SharedWakeAgentJob, context: MatrixStoreContext): Promise<{
+        content: string;
+        [key: string]: unknown;
+    }>;
+    commitResult(roomId: string, job: SharedWakeAgentJob, result: AgentWakeResult, context: MatrixStoreContext): Promise<{
+        eventId: string;
+        run: string;
+    }>;
+    recordFailure(roomId: string, job: SharedWakeAgentJob, failure: {
+        error?: string;
+        retry: boolean;
+    }, context: MatrixStoreContext): Promise<void>;
+}
+/** At-least-once execution: backend result writes and external tools need their own idempotency. */
+export declare class AgentWakeRuntimeService {
+    private readonly queue;
+    private readonly backend;
+    constructor(queue: WakeAgentQueue, backend: AgentWakeRuntimeBackend);
+    claim(request: AgentWakeRequest, context: MatrixStoreContext): Promise<{
+        job: SharedWakeAgentJob | null;
+        input?: {
+            content: string;
+            [key: string]: unknown;
+        };
+    }>;
+    renew(request: AgentWakeLeaseRequest, context: MatrixStoreContext): Promise<{
+        ok: true;
+    }>;
+    fail(request: AgentWakeLeaseRequest & {
+        error?: string;
+        retry?: boolean;
+    }, context: MatrixStoreContext): Promise<{
+        ok: true;
+    }>;
+    complete(request: AgentWakeLeaseRequest & AgentWakeResult, context: MatrixStoreContext): Promise<{
+        eventId: string;
+        run: string;
+    }>;
+    private options;
+    private reference;
+    private activeJob;
+    private assertLease;
+}

package/dist/api/reconciler/AgentWakeRuntimeService.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentWakeRuntimeService = void 0;
+const node_crypto_1 = require("node:crypto");
+const MatrixError_1 = require("../matrix/MatrixError");
+/** At-least-once execution: backend result writes and external tools need their own idempotency. */
+class AgentWakeRuntimeService {
+    constructor(queue, backend) {
+        this.queue = queue;
+        this.backend = backend;
+    }
+    async claim(request, context) {
+        const options = await this.options(request, context);
+        await this.backend.recover(request.roomId, context);
+        const job = await this.queue.claim(options);
+        if (!job) {
+            return { job: null };
+        }
+        try {
+            return { job, input: await this.backend.loadInput(request.roomId, job, context) };
+        }
+        catch (error) {
+            await this.fail({ ...request, id: job.id, fencingToken: job.fencingToken, error: 'Input loading failed', retry: true }, context);
+            throw error;
+        }
+    }
+    async renew(request, context) {
+        this.assertLease(await this.queue.renew(await this.reference(request, context)));
+        return { ok: true };
+    }
+    async fail(request, context) {
+        const reference = await this.reference(request, context);
+        const job = await this.activeJob(reference);
+        // The public runtime contract uses the queue's default three-attempt budget.
+        const retry = request.retry !== false && (job.attempts ?? 0) < 3;
+        await this.backend.recordFailure(request.roomId, job, { error: request.error, retry }, context);
+        this.assertLease(await this.queue.fail({ ...reference, error: request.error, retry }));
+        return { ok: true };
+    }
+    async complete(request, context) {
+        const reference = await this.reference(request, context);
+        const job = await this.activeJob(reference);
+        const result = await this.backend.commitResult(request.roomId, job, {
+            body: request.body, handoffTo: request.handoffTo, evidence: request.evidence,
+        }, context);
+        // A crash after the Pod write causes a replay. The backend must reuse the job's result ID.
+        this.assertLease(await this.queue.complete(reference));
+        return result;
+    }
+    async options(request, context) {
+        if (!context.webId) {
+            throw new MatrixError_1.MatrixError(401, 'M_UNAUTHORIZED', 'Authenticated WebID required');
+        }
+        if (!request.runtimeId || request.runtimeId.length > 128 ||
+            (request.leaseMs !== undefined && (!Number.isSafeInteger(request.leaseMs) || request.leaseMs < 1000 || request.leaseMs > 300_000))) {
+            throw new MatrixError_1.MatrixError(400, 'M_BAD_JSON', 'runtimeId and lease duration are invalid');
+        }
+        const { thread } = await this.backend.authorize(request.roomId, request.agent, context);
+        const clientId = context.auth?.type === 'solid' ? context.auth.clientId ?? '' : '';
+        const owner = (0, node_crypto_1.createHash)('sha256').update(JSON.stringify([context.webId, clientId, request.runtimeId])).digest('hex');
+        return { thread, agent: request.agent, owner, leaseMs: request.leaseMs };
+    }
+    async reference(request, context) {
+        return { ...await this.options(request, context), id: request.id, fencingToken: request.fencingToken };
+    }
+    async activeJob(reference) {
+        this.assertLease(await this.queue.renew(reference));
+        const job = (await this.queue.listQueued(reference.thread, reference.agent)).find(candidate => candidate.status === 'leased' && candidate.id === reference.id && candidate.leaseOwner === reference.owner && candidate.fencingToken === reference.fencingToken);
+        this.assertLease(Boolean(job));
+        return job;
+    }
+    assertLease(valid) {
+        if (!valid) {
+            throw new MatrixError_1.MatrixError(409, 'M_CONFLICT', 'Lease is expired, superseded, or owned by another runtime');
+        }
+    }
+}
+exports.AgentWakeRuntimeService = AgentWakeRuntimeService;
+//# sourceMappingURL=AgentWakeRuntimeService.js.map

package/dist/api/reconciler/AgentWakeRuntimeService.jsonld

@@ -0,0 +1,173 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@undefineds.co/xpod/^0.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:@undefineds.co/xpod",
+  "components": [
+    {
+      "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeService",
+      "@type": "Class",
+      "requireElement": "AgentWakeRuntimeService",
+      "comment": "At-least-once execution: backend result writes and external tools need their own idempotency.",
+      "parameters": [
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeService_queue",
+          "range": "undefineds:dist/api/reconciler/WakeAgentQueue.jsonld#WakeAgentQueue"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeService_backend",
+          "range": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeBackend"
+        }
+      ],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeService__member_queue",
+          "memberFieldName": "queue"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeService__member_backend",
+          "memberFieldName": "backend"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeService__member_constructor",
+          "memberFieldName": "constructor"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeService__member_claim",
+          "memberFieldName": "claim"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeService__member_renew",
+          "memberFieldName": "renew"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeService__member_fail",
+          "memberFieldName": "fail"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeService__member_complete",
+          "memberFieldName": "complete"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeService__member_options",
+          "memberFieldName": "options"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeService__member_reference",
+          "memberFieldName": "reference"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeService__member_activeJob",
+          "memberFieldName": "activeJob"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeService__member_assertLease",
+          "memberFieldName": "assertLease"
+        }
+      ],
+      "constructorArguments": [
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeService_queue"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeService_backend"
+        }
+      ]
+    },
+    {
+      "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRequest",
+      "@type": "AbstractClass",
+      "requireElement": "AgentWakeRequest",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRequest__member_roomId",
+          "memberFieldName": "roomId"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRequest__member_agent",
+          "memberFieldName": "agent"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRequest__member_runtimeId",
+          "memberFieldName": "runtimeId"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRequest__member_leaseMs",
+          "memberFieldName": "leaseMs"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeLeaseRequest",
+      "@type": "AbstractClass",
+      "requireElement": "AgentWakeLeaseRequest",
+      "extends": [
+        "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRequest"
+      ],
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeLeaseRequest__member_id",
+          "memberFieldName": "id"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeLeaseRequest__member_fencingToken",
+          "memberFieldName": "fencingToken"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeResult",
+      "@type": "AbstractClass",
+      "requireElement": "AgentWakeResult",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeResult__member_body",
+          "memberFieldName": "body"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeResult__member_handoffTo",
+          "memberFieldName": "handoffTo"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeResult__member_evidence",
+          "memberFieldName": "evidence"
+        }
+      ],
+      "constructorArguments": []
+    },
+    {
+      "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeBackend",
+      "@type": "AbstractClass",
+      "requireElement": "AgentWakeRuntimeBackend",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeBackend__member_authorize",
+          "memberFieldName": "authorize"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeBackend__member_recover",
+          "memberFieldName": "recover"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeBackend__member_loadInput",
+          "memberFieldName": "loadInput"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeBackend__member_commitResult",
+          "memberFieldName": "commitResult"
+        },
+        {
+          "@id": "undefineds:dist/api/reconciler/AgentWakeRuntimeService.jsonld#AgentWakeRuntimeBackend__member_recordFailure",
+          "memberFieldName": "recordFailure"
+        }
+      ],
+      "constructorArguments": []
+    }
+  ]
+}

package/dist/api/reconciler/ServerGroupReconcilerService.d.ts

@@ -6,9 +6,11 @@ export interface ReconcileGroupThreadMessageInput {
     actor?: string;
     role?: 'user' | 'assistant' | 'system' | string;
     content?: string;
+    createdAt?: string;
     reconcilerOwner?: ReconcilerOwner;
     mentions?: string[];
     routeTargetAgent?: string;
+    /** Authorized wake targets resolved by the caller for this actor and thread. */
     participants?: string[];
 }
 export interface ReconcileGroupThreadMessageResult {
@@ -33,6 +35,7 @@ export declare class ServerGroupReconcilerService {
     private readonly now;
     constructor(options?: ServerGroupReconcilerServiceOptions);
     reconcileThreadMessage(input: ReconcileGroupThreadMessageInput): Promise<ReconcileGroupThreadMessageResult>;
+    getQueue(): WakeAgentQueue;
     listQueued(thread: string, agent?: string): Promise<SharedWakeAgentJob[]>;
     close(): Promise<void>;
 }

package/dist/api/reconciler/ServerGroupReconcilerService.js

@@ -24,6 +24,9 @@ class ServerGroupReconcilerService {
         if (input.role && input.role !== 'user') {
             return { wakeJobs: [], inserted: 0, skippedReason: 'not_user_message' };
         }
+        if (!input.actor?.trim()) {
+            return { wakeJobs: [], inserted: 0, skippedReason: 'missing_actor' };
+        }
         const targets = selectWakeTargets({
             mentions: input.mentions,
             routeTargetAgent: input.routeTargetAgent,
@@ -32,7 +35,7 @@ class ServerGroupReconcilerService {
         if (targets.length === 0) {
             return { wakeJobs: [], inserted: 0, skippedReason: 'no_agent_selected' };
         }
-        const createdAt = this.now().toISOString();
+        const createdAt = input.createdAt ?? this.now().toISOString();
         const jobs = targets.map(({ agent, reason }) => createWakeJob({
             thread: input.thread,
             triggerMessage: input.triggerMessage,
@@ -51,6 +54,9 @@ class ServerGroupReconcilerService {
         }
         return { wakeJobs: enqueued, inserted };
     }
+    getQueue() {
+        return this.wakeQueue;
+    }
     async listQueued(thread, agent) {
         return this.wakeQueue.listQueued(thread, agent);
     }
@@ -69,12 +75,14 @@ function normalizeAgentUris(value) {
     return Array.from(new Set(value.filter((item) => typeof item === 'string' && item.length > 0)));
 }
 function selectWakeTargets(input) {
+    const participants = new Set(normalizeAgentUris(input.participants));
     if (input.routeTargetAgent) {
-        return [{ agent: input.routeTargetAgent, reason: 'manual' }];
+        return participants.has(input.routeTargetAgent)
+            ? [{ agent: input.routeTargetAgent, reason: 'manual' }]
+            : [];
     }
-    const participants = new Set(normalizeAgentUris(input.participants));
     return normalizeAgentUris(input.mentions)
-        .filter((agent) => participants.size === 0 || participants.has(agent))
+        .filter((agent) => participants.has(agent))
         .map((agent) => ({ agent, reason: 'mention' }));
 }
 function createWakeJob(input) {

package/dist/api/reconciler/ServerGroupReconcilerService.jsonld

@@ -40,6 +40,10 @@
           "@id": "undefineds:dist/api/reconciler/ServerGroupReconcilerService.jsonld#ServerGroupReconcilerService__member_reconcileThreadMessage",
           "memberFieldName": "reconcileThreadMessage"
         },
+        {
+          "@id": "undefineds:dist/api/reconciler/ServerGroupReconcilerService.jsonld#ServerGroupReconcilerService__member_getQueue",
+          "memberFieldName": "getQueue"
+        },
         {
           "@id": "undefineds:dist/api/reconciler/ServerGroupReconcilerService.jsonld#ServerGroupReconcilerService__member_listQueued",
           "memberFieldName": "listQueued"
@@ -81,6 +85,10 @@
           "@id": "undefineds:dist/api/reconciler/ServerGroupReconcilerService.jsonld#ReconcileGroupThreadMessageInput__member_content",
           "memberFieldName": "content"
         },
+        {
+          "@id": "undefineds:dist/api/reconciler/ServerGroupReconcilerService.jsonld#ReconcileGroupThreadMessageInput__member_createdAt",
+          "memberFieldName": "createdAt"
+        },
         {
           "@id": "undefineds:dist/api/reconciler/ServerGroupReconcilerService.jsonld#ReconcileGroupThreadMessageInput__member_reconcilerOwner",
           "memberFieldName": "reconcilerOwner"

package/dist/api/reconciler/WakeAgentQueue.d.ts

@@ -3,21 +3,51 @@ export interface WakeAgentEnqueueResult {
     job: SharedWakeAgentJob;
     inserted: boolean;
 }
+export interface WakeAgentClaimOptions {
+    thread: string;
+    agent: string;
+    owner: string;
+    leaseMs?: number;
+}
+export interface WakeAgentLeaseReference extends WakeAgentClaimOptions {
+    id: string;
+    fencingToken: string;
+}
+export interface WakeAgentFailureOptions extends WakeAgentLeaseReference {
+    error?: string;
+    retry?: boolean;
+}
 export interface WakeAgentQueue {
     enqueue(job: SharedWakeAgentJob): Promise<WakeAgentEnqueueResult>;
     listQueued(thread: string, agent?: string): Promise<SharedWakeAgentJob[]>;
+    claim(options: WakeAgentClaimOptions): Promise<SharedWakeAgentJob | undefined>;
+    renew(options: WakeAgentLeaseReference): Promise<boolean>;
+    complete(options: WakeAgentLeaseReference): Promise<boolean>;
+    fail(options: WakeAgentFailureOptions): Promise<boolean>;
     close?(): Promise<void>;
 }
 export interface WakeAgentQueueOptions {
     redisUrl?: string;
     namespace?: string;
+    maxAttempts?: number;
+    now?: () => number;
 }
 export declare function createWakeAgentQueue(options?: WakeAgentQueueOptions): WakeAgentQueue;
 export declare function sharedWakeAgentJobId(input: Pick<SharedWakeAgentJob, 'thread' | 'triggerMessage' | 'agent'>): string;
 export declare function wakeAgentQueueKey(job: Pick<SharedWakeAgentJob, 'thread' | 'agent'>): string;
 export declare class InMemoryWakeAgentQueue implements WakeAgentQueue {
-    private readonly jobsByDedupeKey;
-    private readonly queueKeysByDedupeKey;
+    private readonly jobs;
+    private readonly pending;
+    private readonly now;
+    private readonly maxAttempts;
+    private sequence;
+    constructor(options?: WakeAgentQueueOptions);
     enqueue(job: SharedWakeAgentJob): Promise<WakeAgentEnqueueResult>;
     listQueued(thread: string, agent?: string): Promise<SharedWakeAgentJob[]>;
+    claim(options: WakeAgentClaimOptions): Promise<SharedWakeAgentJob | undefined>;
+    renew(options: WakeAgentLeaseReference): Promise<boolean>;
+    complete(options: WakeAgentLeaseReference): Promise<boolean>;
+    fail(options: WakeAgentFailureOptions): Promise<boolean>;
+    private leased;
+    private finish;
 }