@tangle-network/agent-runtime 0.314.1 → 0.316.0

package/dist/workspace-store/index.d.ts

@@ -0,0 +1,206 @@
+//#region src/workspace-store/store.d.ts
+/**
+ * The workspace store port: path documents with compare-and-set revisions and
+ * erasure tombstones. One store per tenant holds memory and files for every
+ * executor; adapters own persistence, this module owns the contract.
+ *
+ * No `node:` imports: this module runs unchanged in Workers.
+ */
+/** What an entry holds; memory kinds are written through `memory.remember`, files through `files.write`. */
+type WorkspaceEntryKind = 'fact' | 'preference' | 'instruction' | 'file';
+/** `member` entries live under `/memories/members/<memberId>/`; everything else is `workspace`. */
+type WorkspaceEntryScope = 'workspace' | 'member';
+/** Large content kept outside the index, e.g. an R2 object. The adapter owns `key`. */
+interface WorkspaceBytesRef {
+  readonly key: string;
+  readonly size: number;
+  readonly contentType?: string;
+  readonly sha256?: string;
+}
+/** One live document. Exactly one of `content` and `bytes` is present. */
+interface WorkspaceEntry {
+  readonly workspaceId: string;
+  /** Stable for the life of the path; kept across updates. */
+  readonly id: string;
+  readonly path: string;
+  readonly kind: WorkspaceEntryKind;
+  readonly scope: WorkspaceEntryScope;
+  readonly content?: string;
+  readonly bytes?: WorkspaceBytesRef;
+  /** Monotonic per path, including across delete and re-create. */
+  readonly revision: number;
+  readonly createdBy: string;
+  readonly createdAt: string;
+  readonly updatedBy: string;
+  readonly updatedAt: string;
+}
+/** Erasure record: the content and bytes are gone; only this audit row remains. */
+interface WorkspaceTombstone {
+  readonly workspaceId: string;
+  readonly id: string;
+  readonly path: string;
+  /** The revision the delete produced (last live revision + 1). */
+  readonly revision: number;
+  readonly deletedBy: string;
+  readonly deletedAt: string;
+}
+interface WorkspacePutInput {
+  readonly workspaceId: string;
+  readonly path: string;
+  readonly kind: WorkspaceEntryKind;
+  /** Revision the caller read, or `null` when the path must not hold a live entry. */
+  readonly ifRevision: number | null;
+  readonly actor: string;
+  readonly content?: string;
+  readonly bytes?: WorkspaceBytesRef;
+  /** Id for a new entry; ignored on update. Defaults to a random UUID. */
+  readonly id?: string;
+}
+interface WorkspaceDeleteInput {
+  readonly workspaceId: string;
+  readonly path: string;
+  /** When present, the delete is refused unless the live revision matches. */
+  readonly ifRevision?: number;
+  readonly actor: string;
+}
+/**
+ * Versioned path store for one or many tenants. Every write is a compare-and-set
+ * on `revision`; a mismatch throws {@link WorkspaceConflictError}. Delete erases
+ * content and bytes and records a {@link WorkspaceTombstone}.
+ */
+interface WorkspaceStore {
+  get(workspaceId: string, path: string): Promise<WorkspaceEntry | null>;
+  /** Live entries whose path starts with `prefix`, sorted by path. */
+  list(workspaceId: string, prefix: string): Promise<WorkspaceEntry[]>;
+  put(input: WorkspacePutInput): Promise<WorkspaceEntry>;
+  /** Returns the tombstone, or `null` when nothing was live and no `ifRevision` was given. */
+  delete(input: WorkspaceDeleteInput): Promise<WorkspaceTombstone | null>;
+  /** Erasure audit rows whose path starts with `prefix`, oldest first. */
+  tombstones(workspaceId: string, prefix?: string): Promise<WorkspaceTombstone[]>;
+}
+/** A write lost a compare-and-set race or targeted the wrong revision. Re-read and retry. */
+declare class WorkspaceConflictError extends Error {
+  readonly path: string;
+  readonly expected: number | null;
+  readonly actual: number | null;
+  readonly code: "conflict";
+  constructor(path: string, expected: number | null, actual: number | null);
+}
+/** Refuse anything but an absolute, normalized path such as `/files/report.md`. */
+declare function assertWorkspacePath(path: string): void;
+/** The member a path belongs to, or `null` for workspace-scoped paths. */
+declare function memberIdFromPath(path: string): string | null;
+/** Validate a put before any adapter touches storage; adapters call this first. */
+declare function checkWorkspacePut(input: WorkspacePutInput): void;
+/** Process-local adapter for tests, previews, and single-instance hosts. */
+declare function createInMemoryWorkspaceStore(options?: {
+  now?: () => Date;
+  newId?: () => string;
+}): WorkspaceStore;
+//#endregion
+//#region src/workspace-store/contract.d.ts
+interface WorkspaceStoreContractCase {
+  readonly name: string;
+  run(): Promise<void>;
+}
+interface WorkspaceStoreContractResult {
+  readonly name: string;
+  readonly passed: boolean;
+  readonly error?: string;
+}
+/** Make a fresh, empty store for one case. */
+type MakeWorkspaceStore = () => WorkspaceStore | Promise<WorkspaceStore>;
+/** The contract as named cases; each case builds its own store. */
+declare function workspaceStoreContractCases(makeStore: MakeWorkspaceStore): WorkspaceStoreContractCase[];
+/** Run every contract case against fresh stores; never throws for a failing case. */
+declare function runWorkspaceStoreContract(makeStore: MakeWorkspaceStore): Promise<WorkspaceStoreContractResult[]>;
+//#endregion
+//#region src/workspace-store/tools.d.ts
+/** `viewer` and `guest` are read-only under the default policy. */
+type WorkspaceRole = 'owner' | 'manager' | 'member' | 'viewer' | 'guest';
+/** The speaker of the running turn, resolved by the host from its trusted session. */
+interface WorkspaceTurn {
+  readonly workspaceId: string;
+  readonly memberId: string;
+  readonly role: WorkspaceRole;
+}
+/**
+ * Structural tool shape, assignable to agent-app's `McpToolDefinition`
+ * (`name`, `description`, JSON Schema `inputSchema`, `run(args)`), so a host
+ * mounts it in-process or behind `createMcpToolHandler` without this package
+ * depending on agent-app. `run` throws to report a refusal or conflict.
+ */
+interface WorkspaceToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  run(args: Record<string, unknown>): Promise<unknown>;
+}
+interface WorkspaceAccess {
+  readonly op: 'read' | 'write' | 'delete';
+  readonly path: string;
+  readonly kind?: WorkspaceEntryKind;
+}
+/** `null` allows; a string refuses and is shown to the model as the reason. */
+type WorkspacePolicyDecision = string | null;
+interface MemoryPolicy {
+  authorize(turn: WorkspaceTurn, access: WorkspaceAccess): WorkspacePolicyDecision;
+  /** Product content rule, e.g. refuse guest PII. Runs after `authorize` on every write. */
+  admit?(turn: WorkspaceTurn, candidate: {
+    path: string;
+    kind: WorkspaceEntryKind;
+    text: string;
+  }): WorkspacePolicyDecision | Promise<WorkspacePolicyDecision>;
+}
+/** A policy or path rule refused the call. */
+declare class WorkspacePolicyError extends Error {
+  readonly code: "refused";
+  constructor(message: string);
+}
+/**
+ * Default authority. Reads: workspace memory, the speaker's own member memory,
+ * `/knowledge/**`, `/files/**`. Writes: viewers and guests none; any member may
+ * save workspace facts and own-scope facts or preferences, and write `/files/**`;
+ * owners and managers also save instructions, workspace preferences, and
+ * `/knowledge/**`. Nobody touches another member's scope. `admit` is the
+ * product's content hook.
+ */
+declare function defaultMemoryPolicy(options?: {
+  admit?: MemoryPolicy['admit'];
+}): MemoryPolicy;
+interface WorkspaceToolContext {
+  store: WorkspaceStore;
+  /** Resolve the running turn from the trusted server session; never from tool arguments. */
+  activeTurn(): Promise<WorkspaceTurn>;
+  /** Defaults to {@link defaultMemoryPolicy}. */
+  policy?: MemoryPolicy;
+  /** Id for new entries. Defaults to a random UUID. */
+  newId?: () => string;
+}
+/** Workspace memories plus the speaker's own member memories, the set a turn may see. */
+declare function readTurnMemories(store: WorkspaceStore, turn: WorkspaceTurn): Promise<WorkspaceEntry[]>;
+/** `memory.remember`, `memory.recall`, `memory.forget`. */
+declare function createMemoryTools(context: WorkspaceToolContext): WorkspaceToolDefinition[];
+/** `files.list`, `files.read`, `files.write`, `files.delete`, `files.search` over `/files/**` and `/knowledge/**`. */
+declare function createFileTools(context: WorkspaceToolContext): WorkspaceToolDefinition[];
+/**
+ * BM25 over entry text (and path words), highest score first, ties by path.
+ * Entries without inline text match on path words only.
+ */
+declare function rankEntries(entries: readonly WorkspaceEntry[], query: string, limit: number): {
+  entry: WorkspaceEntry;
+  score: number;
+}[];
+/**
+ * Render the memories a turn sees as one stable block for the per-turn preamble.
+ * Order: instructions, preferences, facts; workspace before member; then path.
+ * Input order never changes the output, so identical memories give identical
+ * bytes (cache- and digest-stable). Lines beyond `maxTokens` (≈4 chars per
+ * token) are counted, not shown. The block ends with where to recall more.
+ */
+declare function renderPinnedMemory(entries: readonly WorkspaceEntry[], options?: {
+  maxTokens?: number;
+}): string;
+//#endregion
+export { type MakeWorkspaceStore, type MemoryPolicy, type WorkspaceAccess, type WorkspaceBytesRef, WorkspaceConflictError, type WorkspaceDeleteInput, type WorkspaceEntry, type WorkspaceEntryKind, type WorkspaceEntryScope, type WorkspacePolicyDecision, WorkspacePolicyError, type WorkspacePutInput, type WorkspaceRole, type WorkspaceStore, type WorkspaceStoreContractCase, type WorkspaceStoreContractResult, type WorkspaceTombstone, type WorkspaceToolContext, type WorkspaceToolDefinition, type WorkspaceTurn, assertWorkspacePath, checkWorkspacePut, createFileTools, createInMemoryWorkspaceStore, createMemoryTools, defaultMemoryPolicy, memberIdFromPath, rankEntries, readTurnMemories, renderPinnedMemory, runWorkspaceStoreContract, workspaceStoreContractCases };
+//# sourceMappingURL=index.d.ts.map