attention-manifest-protocol 0.4.2 → 0.4.3

package/lib/file/runtime.js

@@ -0,0 +1,150 @@
+import { fail } from "./errors.js";
+import { PathSandbox } from "./path.js";
+import { WorkspaceTree } from "./tree.js";
+export class SessionRuntime {
+    descriptor;
+    sandbox;
+    store;
+    hostAnnotations;
+    timeZone;
+    followSymlinks;
+    includeHidden;
+    trees = new Map();
+    annotations = new Map();
+    constructor(descriptor, options = {}) {
+        this.descriptor = descriptor;
+        this.sandbox = new PathSandbox(descriptor.roots, { followSymlinks: options.followSymlinks === true });
+        this.store = options.store;
+        this.hostAnnotations = options.annotations ?? {};
+        this.timeZone = options.timeZone === "utc" ? "utc" : "local";
+        this.followSymlinks = options.followSymlinks === true;
+        this.includeHidden = options.includeHidden === true;
+    }
+    /**
+     * Resolve a caller path and return the tree that owns it.
+     */
+    resolve(input, operation) {
+        const rooted = this.sandbox.resolve(input, operation);
+        return { rooted, tree: this.treeFor(rooted.root) };
+    }
+    /**
+     * Resolve and locate one node, failing with `not_found` when it is absent.
+     */
+    node(input, operation = "read") {
+        const { rooted, tree } = this.resolve(input, operation);
+        const node = tree.node(rooted.relative);
+        if (node === (void 0)) {
+            return fail("not_found");
+        }
+        return { rooted, tree, node, revision: tree.revision() };
+    }
+    /**
+     * Cached tree for one root. Options bind the session's own quota, so a
+     * second session cannot raise another's node ceiling.
+     */
+    treeFor(root) {
+        const existing = this.trees.get(root.id);
+        if (existing !== (void 0)) {
+            return existing;
+        }
+        const options = {
+            maxNodes: this.descriptor.permissions.maxTreeNodes,
+            annotations: this.annotationsFor(root),
+            exclude: root.exclude,
+            followSymlinks: this.followSymlinks,
+            includeHidden: this.includeHidden,
+            timeZone: this.timeZone,
+        };
+        const tree = new WorkspaceTree(root, options);
+        this.trees.set(root.id, tree);
+        return tree;
+    }
+    /**
+     * Latest revision of one root, building the tree if necessary.
+     */
+    revisionFor(root) {
+        return this.treeFor(root).revision();
+    }
+    /**
+     * Persist the current snapshot after a write. A store failure is surfaced as
+     * `store_failure`; the in-memory tree stays valid, so a caller can retry the
+     * persistence step without replaying the write.
+     */
+    persist(root, snapshot) {
+        if (this.store === (void 0)) {
+            return;
+        }
+        try {
+            this.store.saveTree(root.id, snapshot);
+        }
+        catch {
+            return fail("store_failure");
+        }
+    }
+    /**
+     * Record one journal entry when a store is configured.
+     */
+    journal(entry) {
+        if (this.store === (void 0)) {
+            return;
+        }
+        try {
+            this.store.appendWrite(entry);
+        }
+        catch {
+            return fail("store_failure");
+        }
+    }
+    /**
+     * Fresh copy of the merged annotations for one root. Stored annotations are
+     * loaded once; host annotations win on a key collision because they are the
+     * more trusted, more recent declaration.
+     */
+    annotationsFor(root) {
+        const existing = this.annotations.get(root.id);
+        if (existing !== (void 0)) {
+            return { ...existing };
+        }
+        const merged = {};
+        if (this.store !== (void 0)) {
+            try {
+                const stored = this.store.loadAnnotations(root.id);
+                Object.assign(merged, stored);
+            }
+            catch {
+                return fail("store_failure");
+            }
+        }
+        const host = this.hostAnnotations[root.id];
+        if (host !== (void 0)) {
+            Object.assign(merged, host);
+        }
+        this.annotations.set(root.id, merged);
+        return { ...merged };
+    }
+    /**
+     * Replace one in-memory annotation after a successful `annotate`-style
+     * write. Kept here so a future annotation tool does not need a second cache.
+     */
+    setAnnotation(root, path, annotation) {
+        const current = this.annotationsFor(root);
+        current[path] = annotation;
+        this.annotations.set(root.id, current);
+        if (this.store !== (void 0)) {
+            try {
+                this.store.saveAnnotation(root.id, path, annotation, "session");
+            }
+            catch {
+                return fail("store_failure");
+            }
+        }
+    }
+    /**
+     * Drop all cached trees and annotations. Called when a session is revoked or
+     * expires so a later session id cannot inherit the old state.
+     */
+    dispose() {
+        this.trees.clear();
+        this.annotations.clear();
+    }
+}

package/lib/file/service.d.ts

@@ -0,0 +1,227 @@
+import { SessionRegistry } from "../session/registry.js";
+import type { SessionDescriptor } from "../session/types.js";
+import type { FilesystemResponse, FilesystemToolDefinition } from "../protocol/filesystem.js";
+import type { SyntaxTree } from "../syntax/syntaxTree.js";
+import type { DependencyGraph } from "./dependency.js";
+import { SessionRuntime } from "./runtime.js";
+import type { AnnotationMap } from "./runtime.js";
+import type { DependencyReport, ExportReport, ImportReport, ReadPage, WriteResult } from "./types.js";
+import type { OutlineResult } from "../outline/types.js";
+/**
+ * Service-wide ceilings. A session's own permissions can only lower them.
+ */
+export interface FilesystemServiceLimits {
+    readonly maxTreeNodes: number;
+    readonly maxReadBytes: number;
+    readonly maxWriteBytes: number;
+    readonly maxResponseChars: number;
+    readonly maxToolCalls: number;
+    readonly maxGraphFiles: number;
+    readonly maxGraphBytes: number;
+}
+/**
+ * Options for the service. `registry` is the only authority source; there is no
+ * path or root input on any tool.
+ */
+export interface FilesystemServiceOptions {
+    readonly registry: SessionRegistry;
+    readonly store?: import("./types.js").FilesystemStore;
+    readonly annotations?: AnnotationMap;
+    readonly limits?: Partial<FilesystemServiceLimits>;
+    readonly timeZone?: "local" | "utc";
+    readonly followSymlinks?: boolean;
+    readonly includeHidden?: boolean;
+}
+/**
+ * Graph cache entry for one root. It is invalidated by the tree revision, not
+ * by time, so a write followed by a query cannot observe stale edges.
+ */
+interface GraphCache {
+    readonly revision: string;
+    readonly graph: DependencyGraph;
+    readonly reports: ReadonlyMap<string, ImportReport>;
+}
+/**
+ * Outline query input accepted by the typed convenience method.
+ */
+export interface OutlineRequest {
+    readonly path: string;
+    readonly maxNodes?: number;
+    readonly maxDepth?: number;
+    readonly symbols?: boolean;
+    readonly query?: string;
+    readonly startLine?: number;
+    readonly endLine?: number;
+}
+/**
+ * Import query input accepted by the typed convenience method.
+ */
+export interface ImportRequest {
+    readonly path: string;
+    readonly direction?: "outgoing" | "incoming" | "both";
+    readonly depth?: number;
+    readonly includeExternal?: boolean;
+    readonly limit?: number;
+}
+/**
+ * Export query input.
+ */
+export interface ExportRequest {
+    readonly path: string;
+    readonly includeReexports?: boolean;
+}
+/**
+ * Syntax tree query. Bounds are passed through to `buildSyntaxTree`.
+ */
+export interface AstRequest {
+    readonly path: string;
+    readonly maxBytes?: number;
+    readonly maxTokens?: number;
+    readonly maxNodes?: number;
+}
+/**
+ * Dependency query input. Roots are root-relative paths, converted to graph ids
+ * inside the service.
+ */
+export interface DependencyQuery {
+    readonly mode: import("./types.js").DependencyMode;
+    readonly roots?: readonly string[];
+    readonly direction?: "dependencies" | "dependents";
+    readonly depth?: number;
+    readonly limit?: number;
+    readonly includeExternal?: boolean;
+}
+export declare class FilesystemService {
+    private readonly registry;
+    private readonly store?;
+    private readonly annotations?;
+    private readonly limits;
+    private readonly timeZone;
+    private readonly followSymlinks;
+    private readonly includeHidden;
+    private readonly runtimes;
+    private readonly graphs;
+    private calls;
+    constructor(options: FilesystemServiceOptions);
+    /**
+     * Authenticate one session and return its handle. A new handle for the same
+     * session shares the runtime so two UI components do not build two trees.
+     */
+    bind(sessionId: string, token: string): FilesystemSession;
+    /**
+     * Drop one session's caches. Hosts call this after revoke/expiry; a later
+     * `bind` recreates the runtime, but the tree is rebuilt from disk rather
+     * than inherited from the previous identity.
+     */
+    /**
+     * Public descriptor view for the `session` tool. Keeps the registry field
+     * private instead of reaching through an index signature from the handle.
+     */
+    summary(sessionId: string): import("../session/types.js").SessionSummary;
+    dispose(sessionId: string): void;
+    /**
+     * JSON-RPC / registry entry. Returns a complete envelope; it never throws.
+     */
+    call(session: FilesystemSession, name: string, raw: unknown): Promise<FilesystemResponse>;
+    /**
+     * Count one business call and enforce the service-wide ceiling.
+     */
+    admit(): void;
+    limitsFor(): FilesystemServiceLimits;
+    /**
+     * Import facts for one file. Office containers are not source text, so they
+     * go through `office.ts` and expose hyperlinks, external workbook links and
+     * embedded objects as external edges instead of failing as binary.
+     */
+    private importReport;
+    /**
+     * Export facts for one file. Office exports are named ranges, bookmarks and
+     * tables; their kind is intentionally generic because the container does not
+     * distinguish a symbol the way a source file does.
+     */
+    private exportReport;
+    /**
+     * Build or reuse the dependency graph for one root. The tree revision is the
+     * cache key; a write refreshes the tree and therefore invalidates the graph.
+     */
+    graphFor(runtime: SessionRuntime, rootId: string): GraphCache;
+    /**
+     * Typed helpers used by the hook layer and direct embedders. They throw the
+     * classified error instead of returning an envelope; the tool surface wraps
+     * them below.
+     */
+    read(runtime: SessionRuntime, request: import("./types.js").ReadRequest): ReadPage;
+    write(runtime: SessionRuntime, request: import("./types.js").WriteRequest): Promise<WriteResult>;
+    outline(runtime: SessionRuntime, request: OutlineRequest): OutlineResult;
+    imports(runtime: SessionRuntime, request: ImportRequest): ImportReport;
+    exports(runtime: SessionRuntime, request: ExportRequest): ExportReport;
+    /**
+     * Lossless syntax tree. Read-only: the parser never imports or evaluates the
+     * target file.
+     */
+    ast(runtime: SessionRuntime, request: AstRequest): SyntaxTree;
+    dependency(runtime: SessionRuntime, request: DependencyQuery): DependencyReport;
+    mapError(error: unknown): import("../protocol/filesystem.js").FilesystemToolErrorCode;
+}
+/**
+ * Bound session handle. It is the only object a transport needs; the token stays
+ * private and is re-checked on every call.
+ */
+export declare class FilesystemSession {
+    readonly sessionId: string;
+    private readonly service;
+    private readonly token;
+    private readonly runtime;
+    private calls;
+    constructor(service: FilesystemService, runtime: SessionRuntime, token: string);
+    get descriptor(): SessionDescriptor;
+    tools(): FilesystemToolDefinition[];
+    /**
+     * Typed read for direct embedders and the hook layer. It throws the
+     * classified error instead of returning the JSON envelope.
+     */
+    read(request: import("./types.js").ReadRequest): ReadPage;
+    /**
+     * Typed write. The only mutating operation in the whole filesystem surface.
+     */
+    write(request: import("./types.js").WriteRequest): Promise<WriteResult>;
+    /**
+     * Typed outline query.
+     */
+    outline(request: OutlineRequest): OutlineResult;
+    /**
+     * Typed import report.
+     */
+    imports(request: ImportRequest): ImportReport;
+    /**
+     * Typed export report.
+     */
+    exports(request: ExportRequest): ExportReport;
+    /**
+     * Typed dependency query.
+     */
+    dependency(request: DependencyQuery): DependencyReport;
+    /**
+     * Typed syntax-tree query. Read-only; the parser never executes the file.
+     */
+    ast(request: AstRequest): SyntaxTree;
+    /**
+     * Current root revision for cache keys and audit rows.
+     */
+    revision(): string;
+    /**
+     * Re-authenticate before each call. A host that revokes or expires a session
+     * therefore does not need to reach into every live handle.
+     */
+    private refresh;
+    dispatch(name: string, raw: unknown): Promise<FilesystemResponse>;
+    private dataFor;
+    private invalid;
+    private revisionOf;
+    errorResponse(code: import("../protocol/filesystem.js").FilesystemToolErrorCode): FilesystemResponse;
+}
+/**
+ * Small helper for hosts that want one descriptor without a live handle.
+ */
+export declare const filesystemSessionSummary: (descriptor: SessionDescriptor) => Record<string, unknown>;
+export {};