@cogenta/agents 0.2.1 → 0.5.0

package/dist/rag/reference-documents/store.d.ts

@@ -0,0 +1,23 @@
+import { type DatabaseHandle } from '@cogenta/core';
+import type { DocumentFormat } from '../../documents/extract-text.js';
+import type { ReferenceDocumentRecord } from './types.js';
+export interface CreateReferenceDocumentInput {
+    readonly siteId: string;
+    readonly filename: string;
+    readonly format: DocumentFormat;
+    readonly characters: number;
+    readonly warnings: readonly string[];
+    readonly uploadedBy: string | null;
+}
+export interface ReferenceDocumentStore {
+    ensureTable(): Promise<void>;
+    list(siteId: string): Promise<readonly ReferenceDocumentRecord[]>;
+    get(siteId: string, id: string): Promise<ReferenceDocumentRecord | null>;
+    /** Inserted with `status: 'pending'` — indexing (embedding + vector upsert) happens after, and reports back via `markIndexed`/`markError`. */
+    create(input: CreateReferenceDocumentInput): Promise<ReferenceDocumentRecord>;
+    markIndexed(siteId: string, id: string, chunkCount: number, at: string): Promise<void>;
+    markError(siteId: string, id: string, message: string): Promise<void>;
+    remove(siteId: string, id: string): Promise<void>;
+}
+export declare function createReferenceDocumentStore(db: DatabaseHandle, now?: () => number): ReferenceDocumentStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/rag/reference-documents/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/rag/reference-documents/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,cAAc,EAMpB,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,KAAK,EAAE,uBAAuB,EAA2B,MAAM,YAAY,CAAA;AAqElF,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CACnC;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,uBAAuB,EAAE,CAAC,CAAA;IACjE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAA;IACxE,8IAA8I;IAC9I,MAAM,CAAC,KAAK,EAAE,4BAA4B,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAA;IAC7E,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtF,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACrE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClD;AAWD,wBAAgB,4BAA4B,CAC1C,EAAE,EAAE,cAAc,EAClB,GAAG,GAAE,MAAM,MAAiB,GAC3B,sBAAsB,CAwFxB"}

package/dist/rag/reference-documents/store.js

@@ -0,0 +1,140 @@
+import { CogentaError, identifier, newId, sql, unsafeRaw, } from '@cogenta/core';
+/**
+ * Metadata for every reference document a site has uploaded — L22 task 4's
+ * "état clair de ce qui est indexé/en cours/en erreur". The vector store
+ * (`VectorStore`) holds the embedded chunks; this table holds the one row
+ * per upload that the admin screen actually renders a list from, because a
+ * `VectorStore` has no notion of "a document", only of chunks that happen to
+ * share an `entryId`.
+ *
+ * Column helpers are written out by hand rather than imported from
+ * `@cogenta/schema`'s `store/columns.ts`: that module is not part of
+ * `@cogenta/schema`'s public `exports` map (only `.` is), and `@cogenta/agents`
+ * may not deep-import another package's `src/`. Three columns' worth of
+ * per-dialect typing is not worth widening that package's public surface for.
+ */
+const REFERENCE_DOCUMENTS_TABLE = 'cogenta_reference_documents';
+function textColumn(dialect, length) {
+    return unsafeRaw(dialect === 'sqlite' ? 'text' : `varchar(${length})`);
+}
+function idColumn(dialect) {
+    if (dialect === 'postgres')
+        return unsafeRaw('uuid');
+    if (dialect === 'mysql')
+        return unsafeRaw('char(36)');
+    return unsafeRaw('text');
+}
+function timestampColumn(dialect) {
+    return textColumn(dialect, 32);
+}
+function integerColumn() {
+    return unsafeRaw('integer');
+}
+function toRecord(row) {
+    return {
+        id: row.id,
+        siteId: row.site_id,
+        filename: row.filename,
+        format: row.format,
+        characters: Number(row.characters),
+        chunkCount: Number(row.chunk_count),
+        status: row.status,
+        errorMessage: row.error_message,
+        warnings: JSON.parse(row.warnings),
+        uploadedAt: row.uploaded_at,
+        uploadedBy: row.uploaded_by,
+        indexedAt: row.indexed_at,
+    };
+}
+function notFound(id) {
+    return new CogentaError({
+        code: 'ASSIST_DOCUMENT_NOT_FOUND',
+        message: `No reference document "${id}" exists on this site.`,
+        hint: 'Check the id against GET /api/assistant/documents — it may already have been removed.',
+        details: { id },
+    });
+}
+export function createReferenceDocumentStore(db, now = Date.now) {
+    const d = db.dialect;
+    const table = identifier(REFERENCE_DOCUMENTS_TABLE, d);
+    return {
+        async ensureTable() {
+            await db.query(sql `
+        create table if not exists ${table} (
+          id ${idColumn(d)} not null primary key,
+          site_id ${textColumn(d, 500)} not null,
+          filename ${textColumn(d, 300)} not null,
+          format ${textColumn(d, 16)} not null,
+          characters ${integerColumn()} not null,
+          chunk_count ${integerColumn()} not null,
+          status ${textColumn(d, 16)} not null,
+          error_message ${textColumn(d, 2000)},
+          warnings ${textColumn(d, 4000)} not null,
+          uploaded_at ${timestampColumn(d)} not null,
+          uploaded_by ${idColumn(d)},
+          indexed_at ${timestampColumn(d)}
+        )`);
+        },
+        async list(siteId) {
+            // `id` (UUIDv7) breaks a tie on `uploaded_at` in the same direction —
+            // two uploads landing in the same millisecond still sort newest first,
+            // deterministically, rather than by whatever order SQLite feels like.
+            const result = await db.query(sql `
+        select * from ${table} where site_id = ${siteId} order by uploaded_at desc, id desc`);
+            return result.rows.map(toRecord);
+        },
+        async get(siteId, id) {
+            const result = await db.query(sql `
+        select * from ${table} where site_id = ${siteId} and id = ${id}`);
+            const row = result.rows[0];
+            return row === undefined ? null : toRecord(row);
+        },
+        async create(input) {
+            const id = newId(now);
+            const uploadedAt = new Date(now()).toISOString();
+            await db.query(sql `
+        insert into ${table}
+          (id, site_id, filename, format, characters, chunk_count, status,
+           error_message, warnings, uploaded_at, uploaded_by, indexed_at)
+        values (
+          ${id}, ${input.siteId}, ${input.filename}, ${input.format}, ${input.characters}, 0,
+          ${'pending'}, ${null}, ${JSON.stringify([...input.warnings])}, ${uploadedAt},
+          ${input.uploadedBy}, ${null}
+        )`);
+            return {
+                id,
+                siteId: input.siteId,
+                filename: input.filename,
+                format: input.format,
+                characters: input.characters,
+                chunkCount: 0,
+                status: 'pending',
+                errorMessage: null,
+                warnings: input.warnings,
+                uploadedAt,
+                uploadedBy: input.uploadedBy,
+                indexedAt: null,
+            };
+        },
+        async markIndexed(siteId, id, chunkCount, at) {
+            await db.query(sql `
+        update ${table}
+        set status = ${'indexed'}, chunk_count = ${chunkCount}, error_message = ${null}, indexed_at = ${at}
+        where site_id = ${siteId} and id = ${id}`);
+        },
+        async markError(siteId, id, message) {
+            await db.query(sql `
+        update ${table}
+        set status = ${'error'}, error_message = ${message}
+        where site_id = ${siteId} and id = ${id}`);
+        },
+        async remove(siteId, id) {
+            const existing = await db.query(sql `
+        select id from ${table} where site_id = ${siteId} and id = ${id}`);
+            if (existing.rows.length === 0)
+                throw notFound(id);
+            await db.query(sql `delete from ${table} where site_id = ${siteId} and id = ${id}`);
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/rag/reference-documents/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/rag/reference-documents/store.ts"],"names":[],"mappings":"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"}

package/dist/rag/reference-documents/types.d.ts

@@ -0,0 +1,52 @@
+import type { DocumentFormat } from '../../documents/extract-text.js';
+/**
+ * L22 task 4 — "un flux d'upload de documents additionnels", wired onto the
+ * existing extraction → chunking → vectorisation pipeline (L19/L18) rather
+ * than a second one.
+ *
+ * A reference document is not content: it has no collection, no locale
+ * variants, no draft/published lifecycle. It still needs a home in the
+ * vector index so `assist.chat` can retrieve it — `VectorRecord` requires a
+ * `collection`/`entryId`/`locale`/`status` (task 5's `VectorScope`), so this
+ * pseudo-collection name is the answer to "what collection is a reference
+ * document in?".
+ *
+ * `^_` can never collide with a real collection name:
+ * `defineCollection`'s own `COLLECTION_NAME_PATTERN` is
+ * `/^[a-z][a-z0-9_]*$/`, which requires a *letter* first. Starting with an
+ * underscore is therefore a name no `defineCollection` call can ever
+ * produce, on any site, without needing a registry or a reserved-word list
+ * kept in sync by hand.
+ */
+export declare const REFERENCE_DOCUMENT_COLLECTION = "_reference_documents";
+/** `locale` a reference document's chunks are stored under — it has no translations, so one sentinel value stands in for "not localised". */
+export declare const REFERENCE_DOCUMENT_LOCALE = "und";
+/**
+ * `status` a reference document's chunks are stored under. Reusing the
+ * content lifecycle's own `'published'` value (rather than inventing a new
+ * one) is what lets `assist.chat`'s hard-coded `status: 'published'` filter
+ * retrieve it with no change to that tool — a reference document is exactly
+ * as quotable as a published entry, the moment it finishes indexing.
+ */
+export declare const REFERENCE_DOCUMENT_STATUS = "published";
+export declare const REFERENCE_DOCUMENT_STATUSES: readonly ['pending', 'indexed', 'error'];
+export type ReferenceDocumentStatus = (typeof REFERENCE_DOCUMENT_STATUSES)[number];
+export interface ReferenceDocumentRecord {
+    readonly id: string;
+    readonly siteId: string;
+    readonly filename: string;
+    readonly format: DocumentFormat;
+    readonly characters: number;
+    /** Chunks actually embedded and stored. `0` until indexing finishes. */
+    readonly chunkCount: number;
+    readonly status: ReferenceDocumentStatus;
+    /** Set only when `status === 'error'`. */
+    readonly errorMessage: string | null;
+    /** `extractDocumentText`'s own warnings (e.g. "PDF page 4 has no text layer") — shown, never hidden. */
+    readonly warnings: readonly string[];
+    readonly uploadedAt: string;
+    readonly uploadedBy: string | null;
+    /** Set once indexing finishes successfully. */
+    readonly indexedAt: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/rag/reference-documents/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/rag/reference-documents/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA;AAErE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,6BAA6B,yBAAyB,CAAA;AAEnE,6IAA6I;AAC7I,eAAO,MAAM,yBAAyB,QAAQ,CAAA;AAE9C;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,cAAc,CAAA;AAEpD,eAAO,MAAM,2BAA2B,YAAI,SAAS,EAAE,SAAS,EAAE,OAAO,CAAU,CAAA;AACnF,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAA;AAElF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAA;IACxC,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,wGAAwG;IACxG,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAClC"}

package/dist/rag/reference-documents/types.js

@@ -0,0 +1,32 @@
+/**
+ * L22 task 4 — "un flux d'upload de documents additionnels", wired onto the
+ * existing extraction → chunking → vectorisation pipeline (L19/L18) rather
+ * than a second one.
+ *
+ * A reference document is not content: it has no collection, no locale
+ * variants, no draft/published lifecycle. It still needs a home in the
+ * vector index so `assist.chat` can retrieve it — `VectorRecord` requires a
+ * `collection`/`entryId`/`locale`/`status` (task 5's `VectorScope`), so this
+ * pseudo-collection name is the answer to "what collection is a reference
+ * document in?".
+ *
+ * `^_` can never collide with a real collection name:
+ * `defineCollection`'s own `COLLECTION_NAME_PATTERN` is
+ * `/^[a-z][a-z0-9_]*$/`, which requires a *letter* first. Starting with an
+ * underscore is therefore a name no `defineCollection` call can ever
+ * produce, on any site, without needing a registry or a reserved-word list
+ * kept in sync by hand.
+ */
+export const REFERENCE_DOCUMENT_COLLECTION = '_reference_documents';
+/** `locale` a reference document's chunks are stored under — it has no translations, so one sentinel value stands in for "not localised". */
+export const REFERENCE_DOCUMENT_LOCALE = 'und';
+/**
+ * `status` a reference document's chunks are stored under. Reusing the
+ * content lifecycle's own `'published'` value (rather than inventing a new
+ * one) is what lets `assist.chat`'s hard-coded `status: 'published'` filter
+ * retrieve it with no change to that tool — a reference document is exactly
+ * as quotable as a published entry, the moment it finishes indexing.
+ */
+export const REFERENCE_DOCUMENT_STATUS = 'published';
+export const REFERENCE_DOCUMENT_STATUSES = ['pending', 'indexed', 'error'];
+//# sourceMappingURL=types.js.map

package/dist/rag/reference-documents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/rag/reference-documents/types.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,sBAAsB,CAAA;AAEnE,6IAA6I;AAC7I,MAAM,CAAC,MAAM,yBAAyB,GAAG,KAAK,CAAA;AAE9C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,WAAW,CAAA;AAEpD,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,CAAU,CAAA"}

package/dist/runtime/loop.d.ts

@@ -1,11 +1,33 @@
-import type { RunAgentLoopInput, RunResult } from './types.js';
+import type { ProviderToolCall } from '../providers/types.js';
+import type { ExecutableTool, RunAgentLoopInput, RunResult, ToolCallOutcome } from './types.js';
 /**
- * L4 task 2: one model call, tool dispatch, repeat — with the three guards
- * the lot's own "pièges connus" call out by name: a step ceiling, repetition
- * detection, and per-call cost (usage) measured from the first line rather
- * than discovered later. Permission checking (task 4) and budgets (task 8)
- * wrap this from the outside; this loop only knows how to hold a
- * conversation with a model and the tools it was handed.
+ * L24 task 1's whole point, made concrete: this function knows nothing about
+ * autonomy, approval, or audit. It is handed whatever `ExecutableTool` its
+ * caller built, and calls `.execute()` on it — nothing more. Contract C's R4
+ * ("un outil déclare ses permissions ; le runtime les vérifie — jamais un
+ * contrôle d'accès à l'intérieur d'un outil") extends unchanged to the graph
+ * era this way: the *tools* node below (the graph's own "inside a node" —
+ * see the task's own wording) is exactly this function wired to LangGraph,
+ * so it inherits the same "zero permission logic" property by construction.
+ * `packages/agents/test/runtime/loop.test.ts`'s "the graph node has no gate
+ * of its own" test calls this directly, once with a tool `withAutonomy`
+ * never touched (to show it *would* run unguarded) and once with the same
+ * tool wrapped (to show the run this package actually produces never can) —
+ * proving the gate lives in the tool object handed in, not in this function.
+ */
+export declare function runTool(tool: ExecutableTool | undefined, call: ProviderToolCall, signal: AbortSignal): Promise<ToolCallOutcome>;
+/**
+ * L4 task 2, migrated to LangGraph.js (L24 task 1): one model call, tool
+ * dispatch, repeat — with the same three guards as before (a step ceiling,
+ * repetition detection, per-call cost measured from the first line), now run
+ * as a two-node `StateGraph` (`buildAgentGraph` above) instead of a `for`
+ * loop. The public contract — `RunAgentLoopInput` in, `RunResult` out — is
+ * unchanged, so every existing caller (`agents/orchestrator.ts`,
+ * `subagents/run-subagent.ts`, `tools/core/agent-delegate.ts`,
+ * `assist/runtime.ts`, `eval/run-suite.ts`) needed no change at all.
+ * Permission checking (task 4, now `withAutonomy`) and budgets (task 8)
+ * still wrap this from the outside; this module still only knows how to
+ * hold a conversation with a model and the tools it was handed.
  */
 export declare function runAgentLoop(input: RunAgentLoopInput): Promise<RunResult>;
 //# sourceMappingURL=loop.d.ts.map

package/dist/runtime/loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/runtime/loop.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAEV,iBAAiB,EACjB,SAAS,EAGV,MAAM,YAAY,CAAA;AAkCnB;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CAoG/E"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/runtime/loop.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAe,gBAAgB,EAAc,MAAM,uBAAuB,CAAA;AAGtF,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,SAAS,EAGT,eAAe,EAChB,MAAM,YAAY,CAAA;AAkBnB;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,cAAc,GAAG,SAAS,EAChC,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,eAAe,CAAC,CAU1B;AAyND;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CAyC/E"}

package/dist/runtime/loop.js

@@ -1,10 +1,13 @@
+import { CogentaError } from '@cogenta/core';
+import { Annotation, END, GraphRecursionError, START, StateGraph } from '@langchain/langgraph';
 import { assertProviderAllowed } from '../privacy/assert-provider-allowed.js';
+import { NOOP_PROGRESS } from '../progress/types.js';
 import { RepetitionGuard } from './repetition.js';
 import { retryModelCall, withTimeout } from './retry.js';
+/** Tool-call step budget and repetition guard — orchestration policy, not a property of any one model, so these stay fixed defaults rather than admin-configurable per provider. */
 const DEFAULT_MAX_STEPS = 25;
-const DEFAULT_MAX_ATTEMPTS = 3;
-const DEFAULT_TIMEOUT_MS = 60_000;
 const DEFAULT_MAX_REPEATS = 2;
+const ZERO_USAGE = { inputTokens: 0, outputTokens: 0 };
 function addUsage(a, b) {
     return {
         inputTokens: a.inputTokens + b.inputTokens,
@@ -14,7 +17,22 @@ function addUsage(a, b) {
 function toolByName(tools) {
     return new Map(tools.map((tool) => [tool.spec.name, tool]));
 }
-async function runTool(tool, call, signal) {
+/**
+ * L24 task 1's whole point, made concrete: this function knows nothing about
+ * autonomy, approval, or audit. It is handed whatever `ExecutableTool` its
+ * caller built, and calls `.execute()` on it — nothing more. Contract C's R4
+ * ("un outil déclare ses permissions ; le runtime les vérifie — jamais un
+ * contrôle d'accès à l'intérieur d'un outil") extends unchanged to the graph
+ * era this way: the *tools* node below (the graph's own "inside a node" —
+ * see the task's own wording) is exactly this function wired to LangGraph,
+ * so it inherits the same "zero permission logic" property by construction.
+ * `packages/agents/test/runtime/loop.test.ts`'s "the graph node has no gate
+ * of its own" test calls this directly, once with a tool `withAutonomy`
+ * never touched (to show it *would* run unguarded) and once with the same
+ * tool wrapped (to show the run this package actually produces never can) —
+ * proving the gate lives in the tool object handed in, not in this function.
+ */
+export async function runTool(tool, call, signal) {
     if (tool === undefined) {
         return { call, ok: false, error: `No tool named "${call.name}" is available in this run.` };
     }
@@ -27,90 +45,237 @@ async function runTool(tool, call, signal) {
     }
 }
 /**
- * L4 task 2: one model call, tool dispatch, repeat — with the three guards
- * the lot's own "pièges connus" call out by name: a step ceiling, repetition
- * detection, and per-call cost (usage) measured from the first line rather
- * than discovered later. Permission checking (task 4) and budgets (task 8)
- * wrap this from the outside; this loop only knows how to hold a
- * conversation with a model and the tools it was handed.
+ * The graph's state. Every field uses LangGraph's default `LastValue`
+ * channel (no reducer) — a node's returned value simply replaces the
+ * previous one, the same "whole new value each time" style the pre-L24
+ * hand-written loop used for its local variables. `pending*` fields are the
+ * only thing carried from the `agent` node to the `tools` node — they hold
+ * exactly what the old loop kept on the stack between "got a response with
+ * tool calls" and "finished executing them".
  */
-export async function runAgentLoop(input) {
+const AgentGraphState = Annotation.Root({
+    messages: Annotation(),
+    steps: Annotation(),
+    usage: Annotation(),
+    finalText: Annotation(),
+    stopReason: Annotation(),
+    stepIndex: Annotation(),
+    pendingAssistant: Annotation(),
+    pendingToolCalls: Annotation(),
+    pendingUsage: Annotation(),
+});
+/**
+ * Builds (and compiles) a fresh two-node graph for one `runAgentLoop` call:
+ * `agent` (one model turn — every guard the old loop checked before calling
+ * the model, then the call itself) and `tools` (executes whatever tool calls
+ * the `agent` node decided to make, via `runTool` above). `agent` is the only
+ * node with an edge back to itself (through `tools`), so "one iteration" of
+ * the old `for` loop is exactly one `agent → tools → agent` cycle here — the
+ * per-iteration guard order (privacy, signal, kill switch, duration, budget,
+ * then the model call) is preserved byte-for-byte because it is still one
+ * function, just called by LangGraph instead of by a `for`.
+ *
+ * Nothing here decides whether a tool call is *allowed* — that decision was
+ * already made (or not) before this function ever sees `input.tools`, by
+ * whoever built that array (`withAutonomyForManifest` in
+ * `agents/orchestrator.ts` for every real caller). The `tools` node below
+ * has no branch for "is this tool allowed" — it cannot have one, because it
+ * never sees a raw tool to begin with.
+ */
+function buildAgentGraph(input) {
     const maxSteps = input.maxSteps ?? DEFAULT_MAX_STEPS;
-    const maxAttempts = input.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
-    const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxAttempts = input.maxAttempts ?? input.client.maxCorrectionAttempts;
+    const timeoutMs = input.timeoutMs ?? input.client.requestTimeoutMs;
     const now = input.now ?? Date.now;
     const tools = input.tools ?? [];
     const toolIndex = toolByName(tools);
     const toolSpecs = tools.length === 0 ? undefined : tools.map((tool) => tool.spec);
     const repetitionGuard = new RepetitionGuard(input.maxRepeats ?? DEFAULT_MAX_REPEATS);
-    const messages = [...input.messages];
-    const steps = [];
-    let totalUsage = { inputTokens: 0, outputTokens: 0 };
-    let finalText = null;
     const runStartedAt = now();
-    for (let step = 0; step < maxSteps; step++) {
+    const progress = input.onProgress ?? NOOP_PROGRESS;
+    async function agentNode(state) {
         if (input.privacyPolicy !== undefined) {
             assertProviderAllowed(input.client, input.privacyPolicy);
         }
-        if (input.signal?.aborted === true) {
-            return { messages, steps, finalText, stopReason: 'cancelled', usage: totalUsage };
-        }
-        if (input.killSwitch?.isActive() === true) {
-            return { messages, steps, finalText, stopReason: 'killed', usage: totalUsage };
-        }
+        if (input.signal?.aborted === true)
+            return { stopReason: 'cancelled' };
+        if (input.killSwitch?.isActive() === true)
+            return { stopReason: 'killed' };
         if (input.maxRunDurationMs !== undefined && now() - runStartedAt >= input.maxRunDurationMs) {
-            return { messages, steps, finalText, stopReason: 'max_duration', usage: totalUsage };
+            return { stopReason: 'max_duration' };
         }
+        if (state.stepIndex >= maxSteps)
+            return { stopReason: 'max_steps' };
         if (input.budget !== undefined) {
             const check = input.budget.checkCall();
             if (!check.allowed) {
                 if (check.reason !== undefined)
                     input.onBudgetExceeded?.(check.reason);
-                return { messages, steps, finalText, stopReason: 'budget_exceeded', usage: totalUsage };
+                return { stopReason: 'budget_exceeded' };
             }
         }
+        progress.report(state.stepIndex === 0 ? 'Thinking…' : `Thinking… (step ${state.stepIndex + 1})`);
         const response = await retryModelCall(() => withTimeout((signal) => input.client.chat({
             model: input.client.model,
             ...(input.system === undefined ? {} : { system: input.system }),
-            messages: [...messages],
+            messages: [...state.messages],
             ...(toolSpecs === undefined ? {} : { tools: toolSpecs }),
-            maxTokens: input.maxTokens,
+            ...(input.maxTokens === undefined ? {} : { maxTokens: input.maxTokens }),
             ...(input.temperature === undefined ? {} : { temperature: input.temperature }),
-        }, { signal }), timeoutMs, input.signal), { maxAttempts });
-        totalUsage = addUsage(totalUsage, response.usage);
+        }, { signal }), timeoutMs, input.signal), {
+            maxAttempts,
+            onRetry: (attempt, error) => progress.report(`Retrying after a provider error (attempt ${attempt}/${maxAttempts}): ${error instanceof Error ? error.message : String(error)}`),
+        });
+        const usage = addUsage(state.usage, response.usage);
         input.budget?.recordCall(response.usage);
         const assistantMessage = {
             role: 'assistant',
             ...(response.content === null ? {} : { content: response.content }),
             ...(response.toolCalls.length === 0 ? {} : { toolCalls: response.toolCalls }),
         };
-        messages.push(assistantMessage);
-        if (response.content !== null)
-            finalText = response.content;
+        const messages = [...state.messages, assistantMessage];
+        const finalText = response.content !== null ? response.content : state.finalText;
+        const stepIndex = state.stepIndex + 1;
         if (response.toolCalls.length === 0) {
-            steps.push({ response: assistantMessage, usage: response.usage, toolOutcomes: [] });
             const stopReason = response.stopReason === 'max_tokens' ? 'max_tokens' : 'end_turn';
-            return { messages, steps, finalText, stopReason, usage: totalUsage };
+            return {
+                messages,
+                finalText,
+                usage,
+                stepIndex,
+                stopReason,
+                steps: [
+                    ...state.steps,
+                    { response: assistantMessage, usage: response.usage, toolOutcomes: [] },
+                ],
+            };
         }
         if (response.toolCalls.some((call) => repetitionGuard.wouldRepeat(call))) {
-            steps.push({ response: assistantMessage, usage: response.usage, toolOutcomes: [] });
-            return { messages, steps, finalText, stopReason: 'repetition_detected', usage: totalUsage };
+            return {
+                messages,
+                finalText,
+                usage,
+                stepIndex,
+                stopReason: 'repetition_detected',
+                steps: [
+                    ...state.steps,
+                    { response: assistantMessage, usage: response.usage, toolOutcomes: [] },
+                ],
+            };
         }
         for (const call of response.toolCalls)
             repetitionGuard.record(call);
+        return {
+            messages,
+            finalText,
+            usage,
+            stepIndex,
+            pendingAssistant: assistantMessage,
+            pendingToolCalls: response.toolCalls,
+            pendingUsage: response.usage,
+        };
+    }
+    async function toolsNode(state) {
         const toolOutcomes = [];
-        for (const call of response.toolCalls) {
+        let messages = state.messages;
+        for (const call of state.pendingToolCalls) {
+            progress.report(`Calling tool "${call.name}"…`);
             const outcome = await runTool(toolIndex.get(call.name), call, input.signal ?? new AbortController().signal);
+            progress.report(outcome.ok
+                ? `Tool "${call.name}" finished.`
+                : `Tool "${call.name}" failed: ${outcome.error ?? 'unknown error'}`);
             toolOutcomes.push(outcome);
-            messages.push({
-                role: 'tool',
-                toolCallId: call.id,
-                toolName: call.name,
-                content: outcome.ok ? (outcome.output ?? '') : `Error: ${outcome.error ?? 'unknown error'}`,
+            messages = [
+                ...messages,
+                {
+                    role: 'tool',
+                    toolCallId: call.id,
+                    toolName: call.name,
+                    content: outcome.ok
+                        ? (outcome.output ?? '')
+                        : `Error: ${outcome.error ?? 'unknown error'}`,
+                },
+            ];
+        }
+        return {
+            messages,
+            steps: [
+                ...state.steps,
+                {
+                    // Set on every path that reaches `tools` (see `agentNode` above) —
+                    // non-null by construction, not by luck.
+                    response: state.pendingAssistant,
+                    usage: state.pendingUsage,
+                    toolOutcomes,
+                },
+            ],
+            pendingAssistant: null,
+            pendingToolCalls: [],
+            pendingUsage: null,
+        };
+    }
+    function routeAfterAgent(state) {
+        return state.stopReason !== null ? END : 'tools';
+    }
+    const graph = new StateGraph(AgentGraphState)
+        .addNode('agent', agentNode)
+        .addNode('tools', toolsNode)
+        .addEdge(START, 'agent')
+        .addConditionalEdges('agent', routeAfterAgent, { tools: 'tools', [END]: END })
+        .addEdge('tools', 'agent');
+    return { graph: graph.compile(), maxSteps };
+}
+/**
+ * L4 task 2, migrated to LangGraph.js (L24 task 1): one model call, tool
+ * dispatch, repeat — with the same three guards as before (a step ceiling,
+ * repetition detection, per-call cost measured from the first line), now run
+ * as a two-node `StateGraph` (`buildAgentGraph` above) instead of a `for`
+ * loop. The public contract — `RunAgentLoopInput` in, `RunResult` out — is
+ * unchanged, so every existing caller (`agents/orchestrator.ts`,
+ * `subagents/run-subagent.ts`, `tools/core/agent-delegate.ts`,
+ * `assist/runtime.ts`, `eval/run-suite.ts`) needed no change at all.
+ * Permission checking (task 4, now `withAutonomy`) and budgets (task 8)
+ * still wrap this from the outside; this module still only knows how to
+ * hold a conversation with a model and the tools it was handed.
+ */
+export async function runAgentLoop(input) {
+    const { graph, maxSteps } = buildAgentGraph(input);
+    const initialState = {
+        messages: [...input.messages],
+        steps: [],
+        usage: ZERO_USAGE,
+        finalText: null,
+        stopReason: null,
+        stepIndex: 0,
+        pendingAssistant: null,
+        pendingToolCalls: [],
+        pendingUsage: null,
+    };
+    let finalState;
+    try {
+        // Generous relative to `maxSteps`: each loop iteration is at most two
+        // graph super-steps (`agent`, then `tools`), and `agentNode`'s own
+        // `stepIndex >= maxSteps` check always produces a `max_steps` stop
+        // before this ceiling could ever bind. It exists as a backstop against a
+        // future bug in that check, not as the mechanism `max_steps` relies on.
+        finalState = await graph.invoke(initialState, { recursionLimit: maxSteps * 2 + 10 });
+    }
+    catch (error) {
+        if (error instanceof GraphRecursionError) {
+            throw new CogentaError({
+                code: 'AGENT_LOOP_RECURSION_LIMIT',
+                message: 'The graph recursion ceiling was hit before its own max_steps check fired.',
+                hint: 'This indicates a bug in the agent graph, not a normal stop reason — please report it.',
             });
         }
-        steps.push({ response: assistantMessage, usage: response.usage, toolOutcomes });
+        throw error;
     }
-    return { messages, steps, finalText, stopReason: 'max_steps', usage: totalUsage };
+    return {
+        messages: finalState.messages,
+        steps: finalState.steps,
+        finalText: finalState.finalText,
+        stopReason: finalState.stopReason ?? 'max_steps',
+        usage: finalState.usage,
+    };
 }
 //# sourceMappingURL=loop.js.map