@feltdb/core 0.13.0 → 0.16.0

package/dist/agent-state.js

@@ -32,6 +32,13 @@ export const FELTDB_AGENT_CHECKPOINT_COLLECTION = '_feltdb.AgentCheckpoint';
 export const FELTDB_AGENT_MEMORY_COLLECTION = '_feltdb.AgentMemory';
 export const FELTDB_AGENT_HANDOFF_COLLECTION = '_feltdb.AgentHandoff';
 export const AGENT_CONTEXT_FORMAT = 'feltdb.agent-context@1';
+/**
+ * Index keys written beside every task head so `listTasks` can filter by
+ * project with an equality prefix. Derived from `scope.project` and `status`
+ * on every task write; never returned as part of an `AgentTask`.
+ */
+const TASK_PROJECT_FIELD = 'list_project';
+const TASK_STATUS_PROJECT_FIELD = 'list_status_project';
 /** Compound indexes every agent-state query is planned against. */
 export const AGENT_STATE_INDEXES = [
     {
@@ -54,9 +61,109 @@ export const AGENT_STATE_INDEXES = [
             persistent: true,
         },
     },
+    // listTasks: one index per filter shape, each led by a distinct field, so
+    // every shape has exactly one compatible plan and none is a residual filter.
+    {
+        collection: FELTDB_AGENT_TASK_COLLECTION,
+        index: {
+            name: 'agent_tasks_by_updated',
+            type: 'compound',
+            fields: ['updated_at', 'id'],
+            directions: ['desc', 'asc'],
+            persistent: true,
+        },
+    },
+    {
+        collection: FELTDB_AGENT_TASK_COLLECTION,
+        index: {
+            name: 'agent_tasks_by_status_updated',
+            type: 'compound',
+            fields: ['status', 'updated_at', 'id'],
+            directions: ['asc', 'desc', 'asc'],
+            persistent: true,
+        },
+    },
+    {
+        collection: FELTDB_AGENT_TASK_COLLECTION,
+        index: {
+            name: 'agent_tasks_by_project_updated',
+            type: 'compound',
+            fields: [TASK_PROJECT_FIELD, 'updated_at', 'id'],
+            directions: ['asc', 'desc', 'asc'],
+            persistent: true,
+        },
+    },
+    {
+        collection: FELTDB_AGENT_TASK_COLLECTION,
+        index: {
+            name: 'agent_tasks_by_status_project_updated',
+            type: 'compound',
+            fields: [TASK_STATUS_PROJECT_FIELD, 'updated_at', 'id'],
+            directions: ['asc', 'desc', 'asc'],
+            persistent: true,
+        },
+    },
+    // listHandoffs
+    {
+        collection: FELTDB_AGENT_HANDOFF_COLLECTION,
+        index: {
+            name: 'agent_handoffs_by_created',
+            type: 'compound',
+            fields: ['created_at', 'id'],
+            directions: ['desc', 'asc'],
+            persistent: true,
+        },
+    },
+    {
+        collection: FELTDB_AGENT_HANDOFF_COLLECTION,
+        index: {
+            name: 'agent_handoffs_by_status_created',
+            type: 'compound',
+            fields: ['status', 'created_at', 'id'],
+            directions: ['asc', 'desc', 'asc'],
+            persistent: true,
+        },
+    },
 ];
+/**
+ * The application-contract entries for agent state.
+ *
+ * An application-scoped authority (Managed FeltDB) stores only collections and
+ * fields its promoted contract declares, so an application that opens agent
+ * state there declares these entries in its contract beside its own, unchanged:
+ * `{ collections: [...mine, ...FELTDB_AGENT_STATE_CONTRACT.collections],
+ * indexes: [...myIndexes, ...FELTDB_AGENT_STATE_CONTRACT.indexes] }`.
+ * Policies stay the application's decision. The record shapes are FeltDB's and
+ * move with it; a test checks that every field agent state writes is declared.
+ */
+export const FELTDB_AGENT_STATE_CONTRACT = (() => {
+    const field = (spec) => {
+        const [name, type] = spec.split(':');
+        return name === 'id'
+            ? { name, type: 'text', required: true, nullable: false }
+            : { name, type, required: false, nullable: true };
+    };
+    const collection = (name, fields) => ({ name, fields: fields.trim().split(/\s+/).map(field) });
+    return Object.freeze({
+        collections: Object.freeze([
+            collection(FELTDB_AGENT_TASK_COLLECTION, `id:text task_id:text objective:text scope:json status:text owner:text
+        checkpoint_version:integer pending_work:json constraints:json created_at:text created_by:text updated_at:text
+        updated_by:text ${TASK_PROJECT_FIELD}:text ${TASK_STATUS_PROJECT_FIELD}:text`),
+            collection(FELTDB_AGENT_CHECKPOINT_COLLECTION, `id:text checkpoint_id:text task_id:text version:integer status:text
+        summary:text completed:json completed_work:json pending_work:json constraints:json decisions:json evidence:json
+        actor:text execution:json created_at:text`),
+            collection(FELTDB_AGENT_MEMORY_COLLECTION, `id:text memory_id:text scope:json scope_key:text kind:text content:json
+        source:json status:text supersedes:text superseded_by:text invalidated_reason:text created_at:text updated_at:text`),
+            collection(FELTDB_AGENT_HANDOFF_COLLECTION, `id:text handoff_id:text task_id:text checkpoint_version:integer from:text
+        to:text note:text memory_refs:json evidence_refs:json artifact_refs:json status:text lease:json claim:json
+        accepted_by:text accepted_at:text created_at:text updated_at:text`),
+        ]),
+        indexes: Object.freeze(AGENT_STATE_INDEXES.map(({ collection, index }) => ({ name: index.name, collection, fields: [...(index.fields ?? [])] }))),
+    });
+})();
 const TASK_STATUSES = ['ready', 'running', 'blocked', 'completed', 'cancelled'];
 const TERMINAL = ['completed', 'cancelled'];
+const HANDOFF_STATUSES = ['open', 'claimed', 'accepted'];
 /** Every refusal. A refused write committed nothing. */
 export class AgentStateError extends Error {
     code;
@@ -150,6 +257,26 @@ function strip(row) {
     const { id: _id, __version, ...rest } = row;
     return { ...rest, revision: typeof __version === 'number' ? __version : 1 };
 }
+/** A task row without its derived index keys. */
+function toTask(row) {
+    const { [TASK_PROJECT_FIELD]: _project, [TASK_STATUS_PROJECT_FIELD]: _statusProject, ...task } = strip(row);
+    return task;
+}
+/** A task head as written: the task plus the index keys `listTasks` filters on. */
+function taskHead(task) {
+    const project = task.scope?.project;
+    return {
+        ...task,
+        ...(project === undefined ? {} : {
+            [TASK_PROJECT_FIELD]: project,
+            [TASK_STATUS_PROJECT_FIELD]: statusProjectKey(task.status, project),
+        }),
+    };
+}
+function statusProjectKey(status, project) {
+    // A status never contains '|', so the first '|' separates the two.
+    return `${status}|${project}`;
+}
 function version(row) {
     return typeof row.__version === 'number' ? row.__version : 1;
 }
@@ -270,7 +397,7 @@ export class AgentStateStore {
         };
         try {
             await this.db.transaction(tx => {
-                tx.collection(FELTDB_AGENT_TASK_COLLECTION).set(taskId, task, { requireAbsent: true });
+                tx.collection(FELTDB_AGENT_TASK_COLLECTION).set(taskId, taskHead(task), { requireAbsent: true });
                 tx.collection(FELTDB_AGENT_CHECKPOINT_COLLECTION).set(checkpoint.checkpoint_id, checkpoint, { requireAbsent: true });
             });
         }
@@ -286,7 +413,7 @@ export class AgentStateStore {
         const row = await this.taskRow(identifier(taskId, 'taskId'));
         if (!row)
             return null;
-        const task = strip(row);
+        const task = toTask(row);
         const checkpoint = await this.getCheckpoint(task.task_id, task.checkpoint_version);
         if (!checkpoint) {
             throw fail('NOT_FOUND', `task ${taskId} names checkpoint ${task.checkpoint_version}, which is not committed`);
@@ -300,6 +427,30 @@ export class AgentStateStore {
         const { revision: _revision, ...checkpoint } = strip(row);
         return checkpoint;
     }
+    /**
+     * One bounded page of tasks, most recently updated first (ties by task id),
+     * optionally narrowed to a status and/or a project.
+     *
+     * Every filter shape is answered by one declared compound index with an
+     * equality prefix; nothing reads the whole collection. Continue with
+     * `cursor: page.nextCursor` and the same filters.
+     */
+    async listTasks(input = {}) {
+        if (input.status !== undefined && !TASK_STATUSES.includes(input.status)) {
+            throw fail('INVALID_REQUEST', `status must be one of ${TASK_STATUSES.join(', ')}`);
+        }
+        const project = input.project === undefined ? undefined : name(input.project, 'project');
+        const where = project === undefined
+            ? (input.status === undefined ? [] : [{ field: 'status', eq: input.status }])
+            : input.status === undefined
+                ? [{ field: TASK_PROJECT_FIELD, eq: project }]
+                : [{ field: TASK_STATUS_PROJECT_FIELD, eq: statusProjectKey(input.status, project) }];
+        const page = await this.page(FELTDB_AGENT_TASK_COLLECTION, where, 'updated_at', input.limit, input.cursor);
+        return {
+            tasks: page.records.map(toTask),
+            ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+        };
+    }
     /**
      * Commit checkpoint N+1 atomically with the task head.
      *
@@ -323,7 +474,7 @@ export class AgentStateStore {
             throw fail('INVALID_REQUEST', `evidence must be an array of at most ${LIST_LIMIT} references`);
         }
         const row = await this.requireTask(id);
-        const task = strip(row);
+        const task = toTask(row);
         if (input.expectedVersion !== undefined && input.expectedVersion !== task.checkpoint_version) {
             throw fail('VERSION_CONFLICT', `task ${id} is at checkpoint ${task.checkpoint_version}, not ${input.expectedVersion}`, {
                 expected: input.expectedVersion, current: task.checkpoint_version,
@@ -369,7 +520,7 @@ export class AgentStateStore {
         };
         try {
             await this.db.transaction(tx => {
-                tx.collection(FELTDB_AGENT_TASK_COLLECTION).set(id, head, { ifVersion: version(row) });
+                tx.collection(FELTDB_AGENT_TASK_COLLECTION).set(id, taskHead(head), { ifVersion: version(row) });
                 tx.collection(FELTDB_AGENT_CHECKPOINT_COLLECTION).set(next.checkpoint_id, next, { requireAbsent: true });
                 for (const entry of cited) {
                     if (entry.evidence.kind === 'record') {
@@ -400,7 +551,7 @@ export class AgentStateStore {
      */
     async resume(taskId, input) {
         const row = await this.requireTask(identifier(taskId, 'taskId'));
-        this.assertOwner(strip(row), name(input.actor, 'actor'));
+        this.assertOwner(toTask(row), name(input.actor, 'actor'));
         return this.assembleContext(taskId, input);
     }
     // --------------------------------------------------------------- memory
@@ -414,7 +565,7 @@ export class AgentStateStore {
         const scopeKey = memoryScopeKey(scope);
         if (taskId || scope.kind === 'task') {
             const owningTask = taskId ?? scope.taskId;
-            const task = strip(await this.requireTask(owningTask));
+            const task = toTask(await this.requireTask(owningTask));
             if (scope.kind === 'task' && scope.taskId !== task.task_id) {
                 throw fail('INVALID_REQUEST', `memory for task ${task.task_id} cannot be written to task scope ${scope.taskId}`);
             }
@@ -481,7 +632,7 @@ export class AgentStateStore {
      * its workspace. A memory scoped to another task is never returned.
      */
     async recallForTask(taskId, input = {}) {
-        const task = strip(await this.requireTask(identifier(taskId, 'taskId')));
+        const task = toTask(await this.requireTask(identifier(taskId, 'taskId')));
         const limit = boundedLimit(input.limit, 20, 100);
         const scopes = [
             { kind: 'task', taskId: task.task_id },
@@ -572,7 +723,7 @@ export class AgentStateStore {
         const actor = name(input.actor, 'actor');
         const to = input.to === undefined ? undefined : name(input.to, 'to');
         const row = await this.requireTask(id);
-        const task = strip(row);
+        const task = toTask(row);
         this.assertOwner(task, actor);
         if (TERMINAL.includes(task.status))
             throw fail('INVALID_TRANSITION', `task ${id} is ${task.status}; it cannot be handed off`);
@@ -633,12 +784,34 @@ export class AgentStateStore {
         }
         return resolveHandoff({ ...record, revision: 1 }, task, checkpoint);
     }
+    /**
+     * One bounded page of handoff records, newest first (ties by handoff id).
+     * `open: true` lists the handoffs nobody has claimed yet. Indexed; never a
+     * collection scan.
+     */
+    async listHandoffs(input = {}) {
+        if (input.open === false) {
+            throw fail('INVALID_REQUEST', "open: false is ambiguous; pass status: 'claimed' or 'accepted'");
+        }
+        if (input.status !== undefined && !HANDOFF_STATUSES.includes(input.status)) {
+            throw fail('INVALID_REQUEST', `status must be one of ${HANDOFF_STATUSES.join(', ')}`);
+        }
+        if (input.open && input.status !== undefined && input.status !== 'open') {
+            throw fail('INVALID_REQUEST', `open: true contradicts status: '${input.status}'`);
+        }
+        const status = input.open ? 'open' : input.status;
+        const page = await this.page(FELTDB_AGENT_HANDOFF_COLLECTION, status === undefined ? [] : [{ field: 'status', eq: status }], 'created_at', input.limit, input.cursor);
+        return {
+            handoffs: page.records.map(row => strip(row)),
+            ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+        };
+    }
     async getHandoff(handoffId) {
         const row = await this.db.collection(FELTDB_AGENT_HANDOFF_COLLECTION).get(identifier(handoffId, 'handoffId', 128));
         if (!row)
             return null;
         const record = strip(row);
-        const task = strip(await this.requireTask(record.task_id));
+        const task = toTask(await this.requireTask(record.task_id));
         const checkpoint = await this.getCheckpoint(record.task_id, record.checkpoint_version);
         if (!checkpoint)
             throw fail('NOT_FOUND', `handoff ${handoffId} references checkpoint ${record.checkpoint_version}, which is not committed`);
@@ -664,7 +837,7 @@ export class AgentStateStore {
         const first = await handoffs.get(id);
         if (!first)
             throw fail('NOT_FOUND', `handoff ${id} does not exist`);
-        const task = strip(await this.requireTask(strip(first).task_id));
+        const task = toTask(await this.requireTask(strip(first).task_id));
         // Decide on a handoff read taken after the task read. A claim commits both
         // records together, so this pair can never show a claimed task beside an
         // open handoff, which would misreport a lost race as a stale handoff.
@@ -710,7 +883,7 @@ export class AgentStateStore {
         try {
             await this.db.transaction(tx => {
                 tx.collection(FELTDB_AGENT_HANDOFF_COLLECTION).set(id, claimed, { ifVersion: handoff.revision });
-                tx.collection(FELTDB_AGENT_TASK_COLLECTION).set(task.task_id, head, { ifVersion: task.revision });
+                tx.collection(FELTDB_AGENT_TASK_COLLECTION).set(task.task_id, taskHead(head), { ifVersion: task.revision });
             });
         }
         catch (error) {
@@ -760,7 +933,7 @@ export class AgentStateStore {
             }
             throw error;
         }
-        const task = strip(await this.requireTask(handoff.task_id));
+        const task = toTask(await this.requireTask(handoff.task_id));
         return this.resolveRecord({ ...accepted, revision: handoff.revision + 1 }, task);
     }
     // -------------------------------------------------------------- context
@@ -894,6 +1067,31 @@ export class AgentStateStore {
         return bundle;
     }
     // ------------------------------------------------------------- internal
+    async page(collection, where, newestFirst, limit, cursor) {
+        if (cursor !== undefined && (typeof cursor !== 'string' || !cursor)) {
+            throw fail('INVALID_REQUEST', 'cursor must be the nextCursor of a previous page');
+        }
+        let page;
+        try {
+            page = await this.db.query({
+                collection,
+                ...(where.length ? { where } : {}),
+                orderBy: [{ field: newestFirst, direction: 'desc' }],
+                limit: boundedLimit(limit, 50, 1_000),
+                ...(cursor ? { cursor } : {}),
+            });
+        }
+        catch (error) {
+            if (/INVALID_CURSOR/.test(error instanceof Error ? error.message : String(error))) {
+                throw fail('INVALID_REQUEST', 'cursor does not belong to this query; pass the nextCursor of a page with the same filters');
+            }
+            throw error;
+        }
+        return {
+            records: page.records,
+            ...(page.nextCursor && !page.exhausted ? { nextCursor: page.nextCursor } : {}),
+        };
+    }
     async taskRow(taskId) {
         return this.db.collection(FELTDB_AGENT_TASK_COLLECTION).get(taskId);
     }

package/dist/agent.d.ts

@@ -19,7 +19,11 @@ export interface AgentRef {
     toString(): string;
 }
 /**
- * Lifecycle states for agent execution
+ * Lifecycle states for agent execution.
+ *
+ * `Completed`, `Failed` and `Cancelled` are terminal. `Cancelled` is reachable
+ * from every non-terminal state, through `AgentRuntime.cancel` or
+ * `transition(execution, Cancelled)`.
  */
 export declare enum AgentExecutionStatus {
     Created = "Created",
@@ -113,6 +117,10 @@ export interface AgentExecution {
     completedMs?: number;
     /** Optional error message if execution failed */
     error?: string;
+    /** The agent-state task this execution works on, when it was created for one. */
+    taskId?: string;
+    /** Why the execution was cancelled (status `Cancelled`). */
+    cancelReason?: string;
     /** Metadata about the execution */
     metadata?: Record<string, any>;
 }
@@ -120,6 +128,7 @@ export interface AgentExecution {
  * Parse an agent reference from its canonical form
  * @example parseAgentRef("flow://agent/researcher@1")
  */
+export declare const AGENT_EXECUTION_TERMINAL_STATUSES: readonly AgentExecutionStatus[];
 export declare function parseAgentRef(ref: string): AgentRef;
 /**
  * Create an agent reference

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/agent.js

@@ -6,7 +6,11 @@
  * of the same causal graph.
  */
 /**
- * Lifecycle states for agent execution
+ * Lifecycle states for agent execution.
+ *
+ * `Completed`, `Failed` and `Cancelled` are terminal. `Cancelled` is reachable
+ * from every non-terminal state, through `AgentRuntime.cancel` or
+ * `transition(execution, Cancelled)`.
  */
 export var AgentExecutionStatus;
 (function (AgentExecutionStatus) {
@@ -25,6 +29,11 @@ export var AgentExecutionStatus;
  * Parse an agent reference from its canonical form
  * @example parseAgentRef("flow://agent/researcher@1")
  */
+export const AGENT_EXECUTION_TERMINAL_STATUSES = [
+    AgentExecutionStatus.Completed,
+    AgentExecutionStatus.Failed,
+    AgentExecutionStatus.Cancelled,
+];
 export function parseAgentRef(ref) {
     const match = ref.match(/^flow:\/\/agent\/([^@]+)@(\d+)$/);
     if (!match) {

package/dist/build-identity.json

@@ -1,13 +1,13 @@
 {
   "schema": "feltdb.build-identity.v2",
   "package": "@feltdb/core",
-  "version": "0.13.0",
+  "version": "0.16.0",
   "git": {
-    "sha1": "b67312f73ea647ffea6f87337303c170d40d541d",
+    "sha1": "2433b73d6e643c8476de7e3364350af0230f47be",
     "dirty": false
   },
   "path_in_vcs": "packages/core",
-  "source_digest": "sha256:7435af3423598673fcce76eb77444ee1e160f39f3fd83a0a788517e315bd3444",
+  "source_digest": "sha256:8bc6dd69a986ac9db9b709570851ebbdf8cdd9ecf2f61e60d21bb8b5c5f1ed9e",
   "inputs": [
     "Cargo.lock",
     "Cargo.toml",
@@ -20,7 +20,15 @@
     "tools/cli",
     "tools/create-feltdb"
   ],
-  "files": 776,
+  "files": 792,
+  "release": {
+    "tag": "v0.16.0",
+    "ref": "main",
+    "origin_main": {
+      "sha1": "2433b73d6e643c8476de7e3364350af0230f47be",
+      "contains_commit": true
+    }
+  },
   "build": {
     "command": "npm run build",
     "node": "v24.9.0"