@anchrd/intel 0.59.0

package/dist/nodes/nodes.types.d.ts

@@ -0,0 +1,511 @@
+import type { SemanticIndex } from "../adapters/semantic-index/semantic-index.types.js";
+import type { Flow, FlowVersion } from "../contract/flow.js";
+import type { ArchiveNodeInput, CreateNodeInput, ListNodesInput, Node, NodeAttachment, NodeCitation, NodeDocument, NodeGraph, NodeGraphInput, NodeKind, NodeLink, NodeTable, NodeVersion, ResolveNodeLinksInput, ResolveNodeLinksResult, SaveAttachmentBytesInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput } from "../contract/node.js";
+import type { ResourceGrant, ResourceGrantList, ResourceVerb, RevokeGrantInput, ShareInput, ShareResult } from "../contract/share.js";
+import type { AppendTableRowsInput, AppendTableRowsResult, DefineTableInput, DeleteTableRowsInput, DeleteTableRowsResult, RedefineTableInput, UpdateTableRowsInput, UpdateTableRowsResult } from "../contract/table.js";
+import type { PromptNameHolder } from "../prompts/prompts.types.js";
+export interface Actor {
+    id: string;
+    email: string;
+    isAdmin?: boolean;
+}
+export interface NewNode {
+    node: Node;
+    actorId: string;
+    idempotencyKey: string;
+    auditId: string;
+}
+export interface NewNodeVersion {
+    version: NodeVersion;
+    actorId: string;
+    baseVersionId: string | null;
+    idempotencyKey: string;
+    auditId: string;
+}
+export interface NewTableVersion {
+    version: Omit<NodeVersion, "sequence">;
+    actorId: string;
+    idempotencyKey: string;
+    auditId: string;
+}
+export type SnapshotOperation = "node.table_update" | "node.table_delete" | "node.table_redefine";
+/**
+ * One version that replaces the readable state, written only against the state it replaces.
+ *
+ * ⚠️ With `sequence` and with `baseVersionId`, unlike the table append. A snapshot replaces what is
+ * read, so it has to know which state it replaces — the same optimistic concurrency the document
+ * save uses, enforced in the same statement that inserts the row (#135).
+ *
+ */
+export interface NewSnapshotVersion {
+    version: NodeVersion;
+    actorId: string;
+    baseVersionId: string | null;
+    operation: SnapshotOperation;
+    metadata: Record<string, unknown>;
+    idempotencyKey: string;
+    auditId: string;
+}
+export interface NodeRepository {
+    listVisible(actor: Actor, input: ListNodesInput): Promise<{
+        items: Node[];
+        withChildren: string[];
+    }>;
+    listVisibleBounded(actor: Actor, input: {
+        parentId: string | null;
+        limit: number;
+    }): Promise<BoundedChildren>;
+    getVisible(actor: Actor, nodeId: string): Promise<Node | null>;
+    listVisibleSubtree(actor: Actor, rootId: string | null): Promise<SubtreeNode[]>;
+    listVisibleAttachments(actor: Actor, input: {
+        limit: number;
+        after: string | null;
+    }): Promise<Node[]>;
+    can(actor: Actor, nodeId: string, verb: ResourceVerb): Promise<boolean>;
+    findIdempotentNode(actorId: string, operation: "node.create" | "node.save" | "node.append" | "node.update" | "node.archive" | "node.share" | "node.revoke" | SnapshotOperation, idempotencyKey: string): Promise<string | null>;
+    findIdempotentRevocation(actorId: string, idempotencyKey: string): Promise<boolean | null>;
+    findSnapshotMetadata(actorId: string, operation: SnapshotOperation, idempotencyKey: string): Promise<Record<string, unknown> | null>;
+    insertNode(input: NewNode): Promise<Node>;
+    getVersion(versionId: string): Promise<NodeVersion | null>;
+    appendVersion(input: NewNodeVersion): Promise<"saved" | "conflict">;
+    appendTableVersion(input: NewTableVersion): Promise<NodeVersion>;
+    appendSnapshotVersion(input: NewSnapshotVersion): Promise<"saved" | "conflict">;
+    listVersionContentKeys(nodeId: string): Promise<string[]>;
+    tableHeaderContentKey(nodeId: string): Promise<string | null>;
+    listVersions(nodeId: string): Promise<NodeVersion[]>;
+    updateNode(input: {
+        node: Node;
+        baseUpdatedAt: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<"cycle" | "conflict" | "prompt_name_taken" | Node>;
+    /**
+     * Who holds a slash command name, for the sentence a refused rename gets (#775). `title` is
+     * `null` when the holder exists but this actor may not see it — the name is taken either way, and
+     * which document it is stays behind the same wall every other read stands behind.
+     */
+    promptNameHolder(actor: Actor, name: string): Promise<PromptNameHolder | null>;
+    archiveNode(input: {
+        nodeId: string;
+        baseUpdatedAt: string;
+        archivedAt: string | null;
+        operationId: string;
+        updatedAt: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<"conflict" | Node>;
+    versionIdsInSubtree(nodeId: string): Promise<string[]>;
+    parentArchivedAt(nodeId: string): Promise<{
+        archivedAt: string | null;
+        kind: string;
+    } | null>;
+    hasAnyChild(nodeId: string): Promise<boolean>;
+    listVectorKeys(nodeId: string): Promise<string[]>;
+    countInboundLinks(nodeId: string): Promise<number>;
+    inspectPurgeTree(nodeId: string): Promise<{
+        nodeIds: string[];
+        named: Array<{
+            id: string;
+            kind: string;
+            title: string;
+        }>;
+        flowIds: string[];
+        contentKeys: string[];
+        vectorKeys: Array<{
+            nodeId: string;
+            keys: string[];
+        }>;
+        counts: Record<string, number>;
+    }>;
+    findPurgeReplay(actorId: string, idempotencyKey: string): Promise<{
+        title: string;
+        contentKeys: string[];
+    } | null>;
+    completePurgeReplay(actorId: string, idempotencyKey: string, completedAt: string): Promise<void>;
+    purgeNode(input: {
+        nodeId: string;
+        actorId: string;
+        auditId: string;
+        occurredAt: string;
+        metadata: Record<string, unknown>;
+        idempotencyKey: string;
+    }): Promise<"missing" | {
+        contentKeys: string[];
+    }>;
+    listGrants(resourceId: string): Promise<ResourceGrant[]>;
+    listEffectiveAccess(resourceId: string): Promise<{
+        ownerIds: string[];
+        items: ResourceGrant[];
+    }>;
+    organizationExecuteReaches(nodeId: string, exceptGrantId: string): Promise<boolean>;
+    listLinksVisible(actor: Actor, nodeId: string): Promise<NodeLink[]>;
+    resolveVisibleTitles(actor: Actor, nodeIds: string[]): Promise<Array<{
+        nodeId: string;
+        title: string;
+    }>>;
+    replaceTextLinks(input: {
+        sourceNodeId: string;
+        links: Array<{
+            id: string;
+            targetNodeId: string;
+        }>;
+        actorId: string;
+        auditId: string;
+        occurredAt: string;
+    }): Promise<void>;
+    graphVisible(actor: Actor, input: NodeGraphInput): Promise<NodeGraph>;
+    setGrant(input: {
+        grant: ResourceGrant;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<ResourceGrant>;
+    revokeGrant(input: {
+        resourceId: string;
+        grantId: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+        occurredAt: string;
+    }): Promise<boolean>;
+    searchVisible(actor: Actor, input: SearchInput): Promise<NodeCitation[]>;
+    /**
+     * `scopeId` cuts the candidates to one folder subtree, which is how the semantic half of a scoped
+     * search is narrowed (#126): the vector index answers over everything and this join is where the
+     * subtree — a relation in D1, not a value on a vector — is applied. The ACL still applies too.
+     *
+     * ⚠️ One entry per node, and it names WHICH chunk answered (anchrd/intel#301). The passage a
+     * searcher is shown is then that card rather than whichever one happens to be first in the board;
+     * a node whose winning chunk has no `node_vectors` row — every vector written before #301 — falls
+     * back on the first full-text passage, which is exactly what this returned before.
+     */
+    hydrateVisibleCitations(actor: Actor, hits: Array<{
+        nodeId: string;
+        chunkKey: string;
+    }>, scopeId?: string): Promise<NodeCitation[]>;
+    invalidateVectors(): Promise<void>;
+    listCurrentVersionIds(input: {
+        after: string | null;
+        limit: number;
+    }): Promise<string[]>;
+    importTree(input: ImportTreeInput): Promise<"created" | "replayed">;
+    findImportReplay(actorId: string, idempotencyKey: string): Promise<Record<string, unknown> | null>;
+}
+export interface ImportedLink {
+    id: string;
+    sourceNodeId: string;
+    targetNodeId: string;
+}
+/**
+ * Everything one bundle import creates, as one write (#137).
+ *
+ * ⚠️ The whole point of this shape is the atomicity: every row lands in one `db.batch`, which D1
+ * runs as one transaction, so a partial import cannot exist — either the whole subtree stands or
+ * nothing does. The R2 objects behind `versions` are written before and deleted again by the
+ * caller when the batch refuses.
+ *
+ * `nodes` must come parents before children: the tree's foreign key checks each row as it lands.
+ */
+export interface ImportTreeInput {
+    nodes: Node[];
+    versions: NodeVersion[];
+    links: ImportedLink[];
+    flows: Flow[];
+    flowVersions: FlowVersion[];
+    actorId: string;
+    idempotencyKey: string;
+    auditId: string;
+    auditResourceId: string;
+    metadata: Record<string, unknown>;
+    occurredAt: string;
+}
+export interface ContentStore {
+    get(key: string): Promise<string | null>;
+    getBytes(key: string): Promise<ArrayBuffer | null>;
+    getStream(key: string): Promise<ReadableStream<Uint8Array> | null>;
+    put(key: string, content: string, mediaType: string): Promise<void>;
+    putBytes(key: string, content: ArrayBuffer, mediaType: string): Promise<void>;
+    /**
+     * One object written from a stream, without the bytes ever standing complete in memory (#821).
+     *
+     * ⚠️ `size` is not a hint, it is the contract with the caller: exactly that many bytes are
+     * expected, and a body that carries more or fewer fails instead of storing a truncated object
+     * under a name that claims to be the file. That is what makes a lying `content-length` a refusal
+     * rather than a corrupt attachment.
+     *
+     * ⚠️ It answers with the hash BECAUSE it streams. Nothing downstream can compute one afterwards
+     * without reading the object back in whole, which is the memory this method exists to avoid, so
+     * the digest is taken as the bytes pass. It is the same hex SHA-256 `hash` produces, and a
+     * version written through either door is comparable with the other.
+     */
+    putStream(key: string, content: ReadableStream<Uint8Array>, mediaType: string, size: number): Promise<{
+        size: number;
+        hash: string;
+    }>;
+    delete(key: string): Promise<void>;
+}
+export interface NodeAttachmentBody {
+    attachment: NodeAttachment;
+    body: ReadableStream<Uint8Array>;
+}
+export interface NodesDeps {
+    repository: NodeRepository;
+    /**
+     * Files a freshly created `task` node on the board it was created under (#648).
+     *
+     * ⚠️ Optional on purpose, and the optionality is the decision rather than a convenience: the node
+     * service is the one path every node takes, including in the CLI and the bundle importer, and
+     * neither of those has a board half of the world. A required port would make "create a node" fail
+     * where boards are not wired — and the answer to a missing board is that a task keeps its node
+     * and gets filed later, never that the node is refused.
+     */
+    attachToBoard?(actor: Actor, taskId: string, boardId: string, occurredAt: string): Promise<void>;
+    /**
+     * Which board a task belongs to (#669).
+     *
+     * ⚠️ Needed since a task may sit under another task: the destination of a move is then not the
+     * board itself, and "does this card change boards" cannot be answered from the node row alone.
+     *
+     * Optional for the same reason as `attachToBoard` — the CLI and the bundle importer have no
+     * board half. ⚠️ **Where it is absent, filing a task UNDER a task is refused** rather than
+     * allowed unchecked: the rule it would skip is the one that keeps a card from silently changing
+     * boards.
+     */
+    boardOfTask?(actor: Actor, taskId: string): Promise<string | null>;
+    content: ContentStore;
+    id(): string;
+    now(): Date;
+    externalFlowCallers(actor: Actor, folderId: string): Promise<{
+        visible: string[];
+        hidden: number;
+    }>;
+    flowNodeReferences(actor: Actor, folderId: string): Promise<string[]>;
+    /**
+     * Published flows that use THIS node as a step (#457).
+     *
+     * ⚠️ Not the same question as `externalFlowCallers`, and the difference cost a refusal that never
+     * fired: that one asks who calls a FLOW filed inside a folder (`kind: "subflow"`,
+     * `configuration.flowId`). A flow reads a NODE through a tree-link step (`configuration
+     * .resourceId`) — a different graph shape entirely, and the one a deletion breaks at run time, in
+     * front of somebody who did not order it.
+     */
+    flowsUsingNode(actor: Actor, nodeId: string): Promise<{
+        visible: string[];
+        hidden: number;
+    }>;
+    /**
+     * The handles of the MCP servers this actor reaches through the portal right now (D30).
+     *
+     * ⚠️ Injected as a live question, never as a stored list. Delegating a server is only allowed to
+     * somebody who has it themselves, and "has it" can only be answered by asking the portal at the
+     * moment of the save — a mirrored table here would be the permission mirror ADR-0003 removed.
+     */
+    toolServers(actor: Actor): Promise<string[]>;
+    hash(content: string | Uint8Array): Promise<string>;
+    indexing: {
+        enqueue(versionId: string): Promise<void>;
+    };
+    semantic?: SemanticIndex | undefined;
+}
+export type FolderAccess = "ok" | "missing" | "not-a-folder" | "forbidden";
+export interface SubtreeNode {
+    node: Node;
+    version: {
+        id: string;
+        mediaType: string;
+        contentKey: string;
+    } | null;
+}
+export interface BoundedChildren {
+    items: Node[];
+    total: number;
+}
+export interface NodeService {
+    list(actor: Actor, input: ListNodesInput): Promise<{
+        items: Node[];
+        withChildren: string[];
+    }>;
+    /**
+     * One level of the tree as this actor may see it, bounded: at most `limit` current children, and
+     * `total` for how many there are. Its caller is the relation graph, which draws a bounded picture
+     * and must not read a folder of a thousand documents to do it (#30).
+     *
+     * ⚠️ `total` counts what passed the visibility predicate and nothing else, or the size a picture
+     * reports would become a way of learning that something is filed here.
+     */
+    childrenBounded(actor: Actor, input: {
+        parentId: string | null;
+        limit: number;
+    }): Promise<BoundedChildren>;
+    get(actor: Actor, nodeId: string): Promise<NodeDocument>;
+    getVersion(actor: Actor, nodeId: string, versionId: string): Promise<NodeDocument>;
+    folderAccess(actor: Actor, folderId: string): Promise<FolderAccess>;
+    create(actor: Actor, input: CreateNodeInput): Promise<Node>;
+    save(actor: Actor, input: SaveNodeVersionInput): Promise<NodeDocument>;
+    saveAttachment(actor: Actor, input: SaveAttachmentInput): Promise<NodeDocument>;
+    /**
+     * The same act as `saveAttachment`, with the bytes arriving as a stream instead of as base64
+     * (#821). It is what the browser uses, and the only door a 50 MB file fits through.
+     *
+     * ⚠️ Every check happens BEFORE the body is touched — visible, an attachment, writable, and the
+     * base version still current. A refusal must not cost 50 MB of transfer, and an unauthorized
+     * caller must not learn the difference between "no such node" and "not yours" by how long the
+     * upload ran.
+     */
+    saveAttachmentBytes(actor: Actor, input: SaveAttachmentBytesInput, body: ReadableStream<Uint8Array>): Promise<NodeDocument>;
+    getTable(actor: Actor, nodeId: string): Promise<NodeTable>;
+    defineTable(actor: Actor, input: DefineTableInput): Promise<NodeTable>;
+    appendTableRows(actor: Actor, input: AppendTableRowsInput): Promise<AppendTableRowsResult>;
+    updateTableRows(actor: Actor, input: UpdateTableRowsInput): Promise<UpdateTableRowsResult>;
+    deleteTableRows(actor: Actor, input: DeleteTableRowsInput): Promise<DeleteTableRowsResult>;
+    redefineTable(actor: Actor, input: RedefineTableInput): Promise<NodeTable>;
+    getAttachment(actor: Actor, nodeId: string): Promise<NodeAttachment>;
+    readAttachment(actor: Actor, nodeId: string): Promise<NodeAttachmentBody>;
+    listAttachments(actor: Actor, input: {
+        limit: number;
+        after: string | null;
+    }): Promise<{
+        items: Node[];
+        nextCursor: string | null;
+    }>;
+    listVersions(actor: Actor, nodeId: string): Promise<{
+        items: NodeVersion[];
+    }>;
+    update(actor: Actor, input: UpdateNodeInput): Promise<Node>;
+    /**
+     * Archiving and restoring, for every kind — and for an agent, its Gate Application with it (#182).
+     *
+     * ⚠️ The Gate call comes FIRST and the node row second. An archived agent whose principal is
+     * still live is exactly the access nobody can see any more, so that state must not be reachable
+     * by a write that half succeeded; the opposite order can only leave a live agent whose principal
+     * is off, which stops working loudly and is repaired by repeating the call.
+     */
+    archive(actor: Actor, input: ArchiveNodeInput): Promise<Node>;
+    purge(actor: Actor, input: {
+        nodeId: string;
+        idempotencyKey: string;
+    }): Promise<{
+        purged: true;
+        title: string;
+    }>;
+    purgePreview(actor: Actor, input: {
+        nodeId: string;
+    }): Promise<{
+        inboundLinks: number;
+        totalItems: number;
+        items: Array<{
+            id: string;
+            kind: NodeKind;
+            title: string;
+        }>;
+    }>;
+    listGrants(actor: Actor, resourceId: string): Promise<ResourceGrantList>;
+    listEffectiveAccess(actor: Actor, resourceId: string): Promise<import("../contract/share.js").ResourceAccessList>;
+    listLinks(actor: Actor, nodeId: string): Promise<{
+        items: NodeLink[];
+    }>;
+    resolveLinks(actor: Actor, input: ResolveNodeLinksInput): Promise<ResolveNodeLinksResult>;
+    graph(actor: Actor, input: NodeGraphInput): Promise<NodeGraph>;
+    visibleNode(actor: Actor, nodeId: string): Promise<Node | null>;
+    share(actor: Actor, input: ShareInput): Promise<ShareResult>;
+    revokeGrant(actor: Actor, input: RevokeGrantInput): Promise<{
+        revoked: boolean;
+    }>;
+    search(actor: Actor, input: SearchInput): Promise<{
+        items: NodeCitation[];
+    }>;
+    reindex(actor: Actor): Promise<{
+        queued: number;
+    }>;
+}
+export interface NodeIndexTarget {
+    nodeId: string;
+    versionId: string;
+    title: string;
+    /**
+     * What a person wrote about the node, and it IS indexed (#816).
+     *
+     * In the full-text row it joins the `content` column beside the title, because it is a sentence
+     * about the node rather than a name: `content` is what the query weights at 1.0 and cuts its
+     * snippet from, while `title` is weighted at 4.0. In the vector index it goes exactly where the
+     * title goes — into the embedded text of the chunk that means the whole node, and nowhere else.
+     *
+     * ⚠️ Until #816 this comment promised the same thing and the code did none of it: the field was
+     * read out of D1, carried here, and then read by nobody. A comment that says the opposite of the
+     * code is worse than none, because it is written into on the strength of a search that cannot
+     * find it.
+     */
+    description: string | null;
+    contentKeys: string[];
+    mediaType: string;
+    /**
+     * How many bytes the current version carries (#821).
+     *
+     * ⚠️ It exists so that the indexer can decide about a file WITHOUT reading it. An attachment is
+     * read into memory whole and handed to the converter as a blob beside it; at 50 MB that is the
+     * isolate's whole budget, and the pass would die at a limit rather than answer. For a table this
+     * is the newest segment alone, which is no answer about the table as a whole — the ceiling below
+     * is an attachment rule and nothing reads this field for another kind.
+     */
+    size: number;
+    kind: Exclude<NodeKind, "folder">;
+    updatedAt: string;
+}
+/**
+ * One passage of a node, as the full-text index holds it.
+ *
+ * ⚠️ A list, and every kind left after #390 puts exactly one in it. It stays a list because the
+ * chunked shape is what `node_fts` and `node_vectors` are built around (#285, anchrd/intel#301) —
+ * the one thing that would have to be rebuilt to unpick it.
+ *
+ * `title` is what the passage is called rather than what the node is called: for a task it is the
+ * task's own title, which is the text the FTS table weights highest.
+ */
+export interface IndexChunk {
+    /**
+     * What this passage is called inside its node (anchrd/intel#301).
+     *
+     * `""` for a node that is one passage, which since #390 is every kind. The full-text index does
+     * not store it; the vector index is NAMED by it, and that is why it stays: the name written
+     * before anchrd/intel#301 is the bare node id, so nothing an installation already holds has to be
+     * renamed or embedded again.
+     */
+    key: string;
+    title: string;
+    text: string;
+}
+/**
+ * What the vector index holds for one chunk of one node (anchrd/intel#301).
+ *
+ * `fingerprint` is over the exact text that was embedded, so the next pass can tell an untouched
+ * card from a changed one without asking Vectorize — whose writes are asynchronous and would answer
+ * about the save before last. `passage` is what a searcher is shown when this vector is the hit.
+ */
+export interface NodeVectorRecord {
+    chunkKey: string;
+    fingerprint: string;
+    passage: string;
+}
+export interface NodeIndexRepository {
+    getTarget(versionId: string): Promise<NodeIndexTarget | null>;
+    /**
+     * The node behind this version when the reason `getTarget` refused it is that the node has been
+     * ARCHIVED — and null for every other reason (anchrd/intel#348).
+     *
+     * ⚠️ The distinction is the whole method. `getTarget` answers null for two very different
+     * situations: the node is archived, or this version has been superseded by a later save. The
+     * first one means "take this node out of the vector index"; the second is a queue message that
+     * arrived late — the ordinary case, because Cloudflare Queues deliver at least once — and acting
+     * on it would delete the vectors of a node that is perfectly alive. So this asks for the archived
+     * case by name and never infers it from an absence.
+     */
+    archivedNodeId(versionId: string): Promise<string | null>;
+    replace(target: NodeIndexTarget, chunks: IndexChunk[]): Promise<void>;
+    listVectors(nodeId: string): Promise<NodeVectorRecord[]>;
+    replaceVectors(target: NodeIndexTarget, records: NodeVectorRecord[]): Promise<void>;
+    deleteVectors(nodeId: string): Promise<void>;
+    markIndexed(versionId: string, occurredAt: string): Promise<void>;
+    markError(versionId: string, message: string, occurredAt: string): Promise<void>;
+}

package/dist/nodes/nodes.types.js

@@ -0,0 +1 @@
+export {};

package/dist/prepare/prepare.d.ts

@@ -0,0 +1,4 @@
+import type { PrepareDeps } from "./prepare.types.js";
+export declare function createPrepare(deps: PrepareDeps): {
+    prepare(): Promise<number>;
+};

package/dist/prepare/prepare.js

@@ -0,0 +1,16 @@
+export function createPrepare(deps) {
+    return {
+        async prepare() {
+            const location = await deps.resolveMigrations();
+            if (!location) {
+                deps.log("Error: @anchrd/intel migrations were not found.");
+                return 1;
+            }
+            const temporaryOutDir = `${location.outDir}.tmp`;
+            await deps.copyDir(location.dir, temporaryOutDir);
+            await deps.replaceDir(temporaryOutDir, location.outDir);
+            deps.log(`Intel migrations copied to ${location.outDir}.`);
+            return 0;
+        },
+    };
+}

package/dist/prepare/prepare.types.d.ts

@@ -0,0 +1,9 @@
+export interface PrepareDeps {
+    resolveMigrations(): Promise<{
+        dir: string;
+        outDir: string;
+    } | null>;
+    copyDir(from: string, to: string): Promise<void>;
+    replaceDir(from: string, to: string): Promise<void>;
+    log(message: string): void;
+}

package/dist/prepare/prepare.types.js

@@ -0,0 +1 @@
+export {};

package/dist/prompts/prompts.d.ts

@@ -0,0 +1,2 @@
+import type { Prompts, PromptsDeps } from "./prompts.types.js";
+export declare function createPrompts(deps: PromptsDeps): Prompts;

package/dist/prompts/prompts.js

@@ -0,0 +1,65 @@
+import { documentText } from "../shared/document-text/document-text.js";
+import { IntelError } from "../shared/intel-error/intel-error.js";
+/**
+ * What a client is handed when it opens the command of a FLOW.
+ *
+ * ⚠️ **This text starts nothing, and that is the point** (D24: the agent acts, Intel does not).
+ * `prompts/get` is a read — a model asked for the wording of a command, not for the command to
+ * happen. Returning instructions rather than performing them keeps the one property that makes
+ * Intel safe to point a model at: nothing in this package moves because something was READ.
+ *
+ * ⚠️ It names the `flowId` rather than the prompt name, because the name is not what the next call
+ * takes. A model handed "run the flow `crm-outreach`" has to translate that back into an id, and
+ * the translation is exactly the step it gets wrong — `flow_run_start` takes an id and refuses a
+ * name with a message about the id being unknown.
+ */
+function flowInstruction(entry) {
+    const description = entry.description === null ? "" : `\n\n${entry.description}`;
+    return `Start the Intel flow "${entry.title}" by calling \`flow_run_start\` with \`flowId: "${entry.targetId}"\`. Do not describe the flow instead of starting it, and do not invent a different id: this one is the flow the command \`/${entry.name}\` stands for.${description}`;
+}
+export function createPrompts(deps) {
+    return {
+        async list(actor) {
+            return await deps.repository.listOffered(actor);
+        },
+        async get(actor, name) {
+            const entry = await deps.repository.findOffered(actor, name);
+            /**
+             * ⚠️ **One refusal for "no such command" and for "not yours to see", and it says the first.**
+             * `findOffered` searches the catalogue as this actor sees it, so a document offered under
+             * this name inside a folder they may not read is simply absent from it. Two different
+             * messages here would make the refusal a way of asking whether a command exists — the same
+             * reading of the tree ADR-0004 §3 refuses everywhere else.
+             */
+            if (entry === null) {
+                throw new IntelError(404, "prompt_not_found", "No command by that name is offered to you. `prompts/list` names the ones that are.");
+            }
+            if (entry.kind === "flow")
+                return { entry, text: flowInstruction(entry) };
+            const document = await deps.readDocument(actor, entry.targetId);
+            /**
+             * ⚠️ **A document with no version yet is an EMPTY command, not a failure.** Somebody offered a
+             * document they have not written in; the honest answer is the empty instruction they have.
+             */
+            if (document.version === null || document.content === null)
+                return { entry, text: "" };
+            /**
+             * ⚠️ **What a document node stores is not its text.** The editor writes a BlockNote payload,
+             * and handing that on gives a model a JSON blob where its instruction should be — for
+             * practically every document written in the app. `documentText` is the same extraction the
+             * search index runs, out of the same function, so the words a model is given and the words
+             * somebody can search for cannot drift apart.
+             */
+            const text = documentText(document.version.mediaType, document.content);
+            /**
+             * ⚠️ And an unreadable payload is REFUSED rather than passed on raw. Half a JSON document as
+             * an instruction is the failure this whole finding is about, one step further along: the
+             * model would act on it rather than report it.
+             */
+            if (text === null) {
+                throw new IntelError(422, "prompt_unreadable", `The document behind /${entry.name} is not stored in a form this command can be read from. Open it once and save it, or offer a document written in the editor.`);
+            }
+            return { entry, text };
+        },
+    };
+}