attention-manifest-protocol 0.4.2 → 0.4.4

package/lib/global/filesystem.js

@@ -0,0 +1,75 @@
+import { GlobalFilesystemProtocol, GlobalFilesystemProtocolVersion, globalFilesystemLocalIds, globalFilesystemToolDefinitions, } from "../protocol/globalFilesystem.js";
+export class GlobalFilesystemService {
+    base;
+    constructor(base) {
+        this.base = base;
+    }
+    /**
+     * Bind one authenticated session to the global namespace.
+     */
+    bind(sessionId, token) {
+        return new GlobalFilesystemSession(this.base.bind(sessionId, token));
+    }
+    dispose(sessionId) {
+        this.base.dispose(sessionId);
+    }
+}
+export class GlobalFilesystemSession {
+    base;
+    constructor(base) {
+        this.base = base;
+    }
+    get sessionId() {
+        return this.base.sessionId;
+    }
+    get descriptor() {
+        return this.base.descriptor;
+    }
+    tools() {
+        return globalFilesystemToolDefinitions();
+    }
+    /**
+     * Typed delegates keep hook and direct-embedder code identical for the
+     * local and global surfaces.
+     */
+    read = (request) => this.base.read(request);
+    write = (request) => this.base.write(request);
+    outline = (request) => this.base.outline(request);
+    imports = (request) => this.base.imports(request);
+    exports = (request) => this.base.exports(request);
+    dependency = (request) => this.base.dependency(request);
+    ast = (request) => this.base.ast(request);
+    revision = () => this.base.revision();
+    async call(name, raw) {
+        const local = globalFilesystemLocalIds.get(name);
+        if (local === (void 0)) {
+            return {
+                protocol: GlobalFilesystemProtocol,
+                version: GlobalFilesystemProtocolVersion,
+                ok: false,
+                revision: `ses.${this.base.descriptor.revision}`,
+                session: this.base.sessionId,
+                error: { code: "unknown_tool", message: "unknown_tool" },
+            };
+        }
+        const response = await this.base.dispatch(local, raw);
+        if ("error" in response) {
+            return {
+                protocol: GlobalFilesystemProtocol,
+                version: GlobalFilesystemProtocolVersion,
+                ok: false,
+                revision: response.revision,
+                session: response.session,
+                error: response.error,
+            };
+        }
+        return {
+            protocol: GlobalFilesystemProtocol,
+            version: GlobalFilesystemProtocolVersion,
+            ok: true,
+            revision: response.revision,
+            session: response.session,
+            data: response.data,
+        };
+    }
+}

package/lib/global/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Global surface: the `amp.workspace` operation set over every authorized
+ * project, exposed as `amp_tool_global_*`.
+ *
+ * Subpath: `attention-manifest-protocol/global`.
+ */
+export * from "./service.js";
+export * from "./filesystem.js";

package/lib/global/index.js

@@ -0,0 +1,8 @@
+/**
+ * Global surface: the `amp.workspace` operation set over every authorized
+ * project, exposed as `amp_tool_global_*`.
+ *
+ * Subpath: `attention-manifest-protocol/global`.
+ */
+export * from "./service.js";
+export * from "./filesystem.js";

package/lib/global/service.d.ts

@@ -0,0 +1,51 @@
+import type { ToolCatalog } from "../naming/index.js";
+import type { WorkspaceRunner, WorkspaceServiceLimits, WorkspaceWriter } from "../context/workspaceService.js";
+import type { ContentStore } from "../context/contentStore.js";
+import type { WorkspaceSnapshot } from "../context/workspace.js";
+import type { HostCatalog } from "../discover/host.js";
+import type { Frame } from "../frame/frame.js";
+import type { ContextSnapshot } from "../context/lifecycle.js";
+import type { Receipt } from "../receipt/receipt.js";
+import type { GlobalResponse } from "../protocol/global.js";
+import type { WorkspaceToolDefinition } from "../protocol/workspace.js";
+export interface GlobalServiceOptions {
+    agentId: string;
+    snapshot: WorkspaceSnapshot;
+    store: ContentStore;
+    /**
+     * Optional narrower project set. Omitted means every project in `snapshot`.
+     */
+    projectIds?: readonly string[];
+    host?: HostCatalog;
+    limits?: Partial<WorkspaceServiceLimits>;
+    /**
+     * Optional persistence port forwarded to the underlying workspace service.
+     * Without it the global write tool answers `write_unavailable`, exactly as
+     * the workspace-scoped surface does.
+     */
+    writer?: WorkspaceWriter;
+    /**
+     * Optional execution port forwarded to the underlying workspace service.
+     * Without it `build`/`compile`/`run`/`test` answer `run_unavailable`.
+     */
+    runner?: WorkspaceRunner;
+}
+export declare class GlobalAgentService {
+    private readonly workspace;
+    private readonly definitions;
+    private readonly revision;
+    private cachedCatalog;
+    constructor(options: GlobalServiceOptions);
+    tools(): WorkspaceToolDefinition[];
+    catalog(): ToolCatalog;
+    call(name: string, raw: unknown): GlobalResponse;
+    registerFrame(frame: Frame, revision: string): void;
+    revokeFrame(frameId: string): void;
+    settle(contextId: string, receipt: Receipt): ContextSnapshot;
+    pendingSettlements(): Array<{
+        contextId: string;
+        frameId: string;
+        estimatedTokens: number;
+    }>;
+    private error;
+}

package/lib/global/service.js

@@ -0,0 +1,98 @@
+/**
+ * Global agent service: the `amp.workspace` operation set over every
+ * host-authorized project, exposed under the `amp_tool_global_*` names.
+ *
+ * This is a thin adapter, not a second implementation. The underlying
+ * `WorkspaceAgentService` receives the complete project set; the adapter
+ * rewrites names, the protocol envelope and the capabilities catalog so a
+ * client sees the global surface consistently.
+ */
+import { buildCatalog } from "../naming/index.js";
+import { digestOf } from "../semantic/canonical.js";
+import { WorkspaceAgentService } from "../context/workspaceService.js";
+import { GlobalProtocol, GlobalProtocolVersion, globalToolDefinitions, globalToolLeaves } from "../protocol/global.js";
+export class GlobalAgentService {
+    workspace;
+    definitions = globalToolDefinitions();
+    revision;
+    cachedCatalog;
+    constructor(options) {
+        const projectIds = options.projectIds ?? options.snapshot.entities.filter((entity) => entity.kind === "project").map((entity) => entity.id);
+        this.revision = options.snapshot.revision;
+        this.workspace = new WorkspaceAgentService({
+            agentId: options.agentId,
+            snapshot: options.snapshot,
+            projectIds,
+            store: options.store,
+            ...(options.host === (void 0) ? {} : { host: options.host }),
+            ...(options.limits === (void 0) ? {} : { limits: options.limits }),
+            ...(options.writer === (void 0) ? {} : { writer: options.writer }),
+            ...(options.runner === (void 0) ? {} : { runner: options.runner }),
+        });
+    }
+    tools() {
+        return structuredClone(this.definitions);
+    }
+    catalog() {
+        if (this.cachedCatalog === (void 0)) {
+            const entries = this.definitions.map((tool) => ({
+                id: tool.name,
+                digest: digestOf({ description: tool.description, inputSchema: tool.inputSchema, risk: tool.risk }),
+                risk: tool.risk,
+            }));
+            this.cachedCatalog = buildCatalog(entries, { version: "1.0.0", ttlMs: 0, cacheScope: "private" });
+        }
+        return structuredClone(this.cachedCatalog);
+    }
+    call(name, raw) {
+        const leaf = globalToolLeaves.get(name);
+        if (leaf === (void 0)) {
+            return this.error("unknown_tool", "unknown_tool");
+        }
+        const response = this.workspace.call(`amp_tool_workspace_${leaf}`, raw);
+        if ("error" in response) {
+            return {
+                protocol: GlobalProtocol,
+                version: GlobalProtocolVersion,
+                revision: response.revision,
+                ok: false,
+                error: response.error,
+            };
+        }
+        const data = { ...response.data };
+        if (leaf === "capabilities") {
+            data.tools = this.definitions.map((tool) => tool.name);
+            const catalog = this.catalog();
+            data.catalog = { version: catalog.version, digest: catalog.digest, sortedBy: catalog.sortedBy, ttlMs: catalog.ttlMs };
+            data.deprecatedAliases = [];
+        }
+        return {
+            protocol: GlobalProtocol,
+            version: GlobalProtocolVersion,
+            revision: response.revision,
+            ok: true,
+            data,
+        };
+    }
+    registerFrame(frame, revision) {
+        this.workspace.registerFrame(frame, revision);
+    }
+    revokeFrame(frameId) {
+        this.workspace.revokeFrame(frameId);
+    }
+    settle(contextId, receipt) {
+        return this.workspace.settle(contextId, receipt);
+    }
+    pendingSettlements() {
+        return this.workspace.pendingSettlements();
+    }
+    error(code, message) {
+        return {
+            protocol: GlobalProtocol,
+            version: GlobalProtocolVersion,
+            revision: this.revision,
+            ok: false,
+            error: { code, message },
+        };
+    }
+}

package/lib/governance/transport.js

@@ -81,8 +81,13 @@ export class HttpCooperationTransport {
 export const createCooperationHandler = (bus, options = {}) => {
     const replay = new ReplayGuard();
     const now = options.now ?? (() => Date.now());
-    const maxSkewMs = Math.max(1_000, options.maxSkewMs ?? 60_000);
-    const replayWindowMs = Math.max(maxSkewMs, options.replayWindowMs ?? 5 * 60_000);
+    const configuredSkew = options.maxSkewMs ?? 60_000;
+    const configuredWindow = options.replayWindowMs ?? 5 * 60_000;
+    if (!Number.isFinite(configuredSkew) || configuredSkew < 0 || !Number.isFinite(configuredWindow) || configuredWindow < 0) {
+        throw new RangeError("transport replay windows must be finite and non-negative");
+    }
+    const maxSkewMs = Math.max(1_000, configuredSkew);
+    const replayWindowMs = Math.max(maxSkewMs, configuredWindow);
     return async (body) => {
         if (!isRecord(body) || !isRecord(body.message)) {
             return {
@@ -92,7 +97,11 @@ export const createCooperationHandler = (bus, options = {}) => {
         }
         if (options.keyring !== (void 0)) {
             const auth = body.auth;
-            if (!isRecord(auth) || typeof (auth.signer) !== "string" || typeof (auth.signature) !== "string" || typeof (auth.timestamp) !== "string" || typeof (auth.nonce) !== "string") {
+            if (!isRecord(auth) ||
+                typeof (auth.signer) !== "string" ||
+                typeof (auth.signature) !== "string" ||
+                typeof (auth.timestamp) !== "string" ||
+                typeof (auth.nonce) !== "string") {
                 return { status: 401, body: { ok: false, code: "transport-error", detail: "missing transport authentication" } };
             }
             const candidates = options.keyring.candidates(auth.signer, auth.kid);
@@ -101,12 +110,12 @@ export const createCooperationHandler = (bus, options = {}) => {
             }
             const timestamp = Date.parse(auth.timestamp);
             const current = now();
+            if (!Number.isFinite(current)) {
+                return { status: 500, body: { ok: false, code: "transport-error", detail: "transport clock is invalid" } };
+            }
             if (!Number.isFinite(timestamp) || Math.abs(current - timestamp) > maxSkewMs) {
                 return { status: 409, body: { ok: false, code: "transport-error", detail: "transport timestamp is outside the allowed skew" } };
             }
-            if (!replay.accept(auth.nonce, current, replayWindowMs)) {
-                return { status: 409, body: { ok: false, code: "transport-error", detail: "transport nonce was already used" } };
-            }
             let valid = false;
             for (let index = 0; index < candidates.length; index += 1) {
                 if (await verifyCanonicalValue({ message: body.message, signer: auth.signer, timestamp: auth.timestamp, nonce: auth.nonce }, auth.signature, candidates[index])) {
@@ -117,6 +126,9 @@ export const createCooperationHandler = (bus, options = {}) => {
             if (!valid) {
                 return { status: 401, body: { ok: false, code: "transport-error", detail: "transport signature does not verify" } };
             }
+            if (!replay.accept(auth.nonce, current, replayWindowMs)) {
+                return { status: 409, body: { ok: false, code: "transport-error", detail: "transport nonce was already used" } };
+            }
         }
         const delivery = bus.receive(body.message);
         return { status: delivery.ok ? 200 : 422, body: delivery };

package/lib/hook/ast.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Syntax-tree hooks.
+ *
+ * The parse helper exposes the lossless CST directly; `useAst` adds the standard
+ * hook state, cache and audit record. Both are read-only: the parser never
+ * evaluates or imports the target file.
+ */
+import type { AstRequest } from "../file/service.js";
+import type { SyntaxTree } from "../syntax/syntaxTree.js";
+import type { Hook, HookOptions, HookSession } from "./types.js";
+/**
+ * Parse helper shape.
+ */
+export type AstParse = (path: string, options?: Omit<AstRequest, "path">) => SyntaxTree;
+/**
+ * Parse one file into a syntax tree without hook state.
+ *
+ * @param session - Bound filesystem session.
+ * @returns Parse helper.
+ */
+export declare const useParse: (session: HookSession) => AstParse;
+/**
+ * Syntax-tree hook.
+ *
+ * @param session - Bound filesystem session.
+ * @param options - Recorder and cache options.
+ * @returns Hook producing one syntax tree.
+ */
+export declare const useAst: (session: HookSession, options?: HookOptions) => Hook<AstRequest, SyntaxTree>;

package/lib/hook/ast.js

@@ -0,0 +1,22 @@
+import { createHook } from "./types.js";
+/**
+ * Parse one file into a syntax tree without hook state.
+ *
+ * @param session - Bound filesystem session.
+ * @returns Parse helper.
+ */
+export const useParse = (session) => (path, options = {}) => session.ast({ path, ...options });
+/**
+ * Syntax-tree hook.
+ *
+ * @param session - Bound filesystem session.
+ * @param options - Recorder and cache options.
+ * @returns Hook producing one syntax tree.
+ */
+export const useAst = (session, options = {}) => createHook({
+    name: "ast",
+    session,
+    execute: (request) => session.ast(request),
+    pathOf: (request) => request.path,
+    options,
+});

package/lib/hook/code.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Code model hook.
+ *
+ * A code model is the smallest set of facts an agent needs before editing a
+ * file: what language and content it is, what structure it has, what it imports
+ * and what it exports. The model is assembled from the three service methods
+ * (`outline`, `imports`, `exports`) and never from a second parser; the outline
+ * already carries the fingerprint and the language tag, so the three parts
+ * cannot disagree about which file version they describe.
+ *
+ * The model is deliberately not cached across paths: a caller asks for one
+ * path, and the hook layer's optional cache keyed by the request handles
+ * repetition.
+ */
+import type { ExportReport, ImportReport } from "../file/types.js";
+import type { OutlineResult } from "../outline/types.js";
+import type { Hook, HookOptions, HookSession } from "./types.js";
+/**
+ * Complete model for one source file.
+ */
+export interface CodeModel {
+    readonly path: string;
+    readonly language: string;
+    readonly fingerprint: string;
+    readonly outline: OutlineResult;
+    readonly imports: ImportReport;
+    readonly exports: ExportReport;
+}
+/**
+ * Request accepted by `useCode`.
+ */
+export interface CodeRequest {
+    readonly path: string;
+    readonly maxNodes?: number;
+    readonly maxDepth?: number;
+}
+/**
+ * Parse helper shape: one path in, one code model out.
+ */
+export type CodeParse = (path: string) => CodeModel;
+/**
+ * Read the complete code model for one path.
+ *
+ * @param session - Bound filesystem session.
+ * @returns Parse helper.
+ */
+export declare const useParse: (session: HookSession) => CodeParse;
+/**
+ * Code model hook.
+ *
+ * @param session - Bound filesystem session.
+ * @param options - Recorder and cache options.
+ * @returns Hook producing one code model.
+ */
+export declare const useCode: (session: HookSession, options?: HookOptions) => Hook<CodeRequest, CodeModel>;

package/lib/hook/code.js

@@ -0,0 +1,47 @@
+import { createHook } from "./types.js";
+/**
+ * Build a code model from the service methods. This is the single assembly
+ * point used by both the parse helper and the hook.
+ *
+ * @param session - Bound filesystem session.
+ * @param request - Path and optional outline bounds.
+ * @returns The assembled model.
+ */
+const codeModelOf = (session, request) => {
+    const outline = session.outline({
+        path: request.path,
+        ...(request.maxNodes === (void 0) ? {} : { maxNodes: request.maxNodes }),
+        ...(request.maxDepth === (void 0) ? {} : { maxDepth: request.maxDepth }),
+    });
+    const imports = session.imports({ path: request.path });
+    const exports = session.exports({ path: request.path });
+    return {
+        path: request.path,
+        language: outline.language,
+        fingerprint: outline.fingerprint,
+        outline,
+        imports,
+        exports,
+    };
+};
+/**
+ * Read the complete code model for one path.
+ *
+ * @param session - Bound filesystem session.
+ * @returns Parse helper.
+ */
+export const useParse = (session) => (path) => codeModelOf(session, { path });
+/**
+ * Code model hook.
+ *
+ * @param session - Bound filesystem session.
+ * @param options - Recorder and cache options.
+ * @returns Hook producing one code model.
+ */
+export const useCode = (session, options = {}) => createHook({
+    name: "code",
+    session,
+    execute: (request) => codeModelOf(session, request),
+    pathOf: (request) => request.path,
+    options,
+});

package/lib/hook/dependency.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Dependency hooks.
+ *
+ * Two layers are exposed. `useParse` is a plain read helper that returns the
+ * import and export reports for one path; it exists so a caller that only needs
+ * facts does not have to create a hook or subscribe to state. `useDependency`
+ * wraps the graph query itself and keeps its bounded report observable.
+ *
+ * Both layers call the session methods directly. No graph algorithm is
+ * re-implemented here: the service already owns the import graph cache, cycle
+ * detection, topological order and closures, and duplicating any of that would
+ * create two answers to "what depends on this?".
+ */
+import type { DependencyQuery } from "../file/service.js";
+import type { DependencyReport, ExportReport, ImportReport } from "../file/types.js";
+import type { Hook, HookOptions, HookSession } from "./types.js";
+/**
+ * Facts returned by the dependency parse helper.
+ */
+export interface DependencyFacts {
+    readonly path: string;
+    readonly imports: ImportReport;
+    readonly exports: ExportReport;
+}
+/**
+ * Parse helper shape: one path in, both reports out.
+ */
+export type DependencyParse = (path: string) => DependencyFacts;
+/**
+ * Read the import and export reports for one path. Both calls are read-only and
+ * use the session's outgoing direction.
+ *
+ * @param session - Bound filesystem session.
+ * @returns Parse helper.
+ */
+export declare const useParse: (session: HookSession) => DependencyParse;
+/**
+ * Dependency graph hook. The request is passed through unchanged, including
+ * `roots`, `direction`, `depth`, `limit` and `includeExternal`.
+ *
+ * @param session - Bound filesystem session.
+ * @param options - Recorder and cache options.
+ * @returns Hook producing a bounded dependency report.
+ */
+export declare const useDependency: (session: HookSession, options?: HookOptions) => Hook<DependencyQuery, DependencyReport>;

package/lib/hook/dependency.js

@@ -0,0 +1,28 @@
+import { createHook } from "./types.js";
+/**
+ * Read the import and export reports for one path. Both calls are read-only and
+ * use the session's outgoing direction.
+ *
+ * @param session - Bound filesystem session.
+ * @returns Parse helper.
+ */
+export const useParse = (session) => (path) => {
+    const imports = session.imports({ path });
+    const exports = session.exports({ path });
+    return { path, imports, exports };
+};
+/**
+ * Dependency graph hook. The request is passed through unchanged, including
+ * `roots`, `direction`, `depth`, `limit` and `includeExternal`.
+ *
+ * @param session - Bound filesystem session.
+ * @param options - Recorder and cache options.
+ * @returns Hook producing a bounded dependency report.
+ */
+export const useDependency = (session, options = {}) => createHook({
+    name: "dependency",
+    session,
+    execute: (request) => session.dependency(request),
+    pathOf: (request) => request.roots?.[0],
+    options,
+});

package/lib/hook/diff.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Diff line kind. `context` lines are equal on both sides.
+ */
+export type DiffLineType = "add" | "remove" | "context";
+/**
+ * One diff line. See the module comment for the coordinate rules.
+ */
+export interface DiffLine {
+    readonly type: DiffLineType;
+    readonly text: string;
+    readonly beforeLine: number;
+    readonly afterLine: number;
+}
+/**
+ * One contiguous changed region plus its context lines.
+ */
+export interface DiffHunk {
+    readonly beforeStart: number;
+    readonly beforeLines: number;
+    readonly afterStart: number;
+    readonly afterLines: number;
+    readonly lines: readonly DiffLine[];
+}
+/**
+ * Request accepted by `useDiff`. `before` overrides the current file as the
+ * old side, and `content` overrides it as the new side; an omitted side is
+ * read from the session. With both omitted the file is compared against itself
+ * and therefore has no hunks.
+ */
+export interface DiffRequest {
+    readonly path: string;
+    readonly content?: string;
+    readonly before?: string;
+    readonly context?: number;
+}
+/**
+ * Complete diff result.
+ */
+export interface DiffResult {
+    readonly path: string;
+    readonly beforeFingerprint: string;
+    readonly afterFingerprint: string;
+    readonly added: number;
+    readonly removed: number;
+    readonly unchanged: number;
+    readonly hunks: readonly DiffHunk[];
+    readonly truncated: boolean;
+}
+/**
+ * One side of a diff. Fingerprints and truncation are carried explicitly so a
+ * caller that read the file page by page does not have to reconstruct them.
+ */
+export interface DiffSource {
+    readonly lines: readonly string[];
+    readonly fingerprint: string;
+    readonly truncated: boolean;
+}
+/**
+ * Options for a diff computation.
+ */
+export interface DiffOptions {
+    readonly context?: number;
+}
+/**
+ * Maximum number of lines diffed per side. Beyond this the computation is
+ * bounded and the result says `truncated`.
+ */
+export declare const DiffMaxLines: number;
+/**
+ * Default number of unchanged lines kept on each side of a change.
+ */
+export declare const DiffDefaultContext: number;
+/**
+ * Hard ceiling for a caller-supplied context size.
+ */
+export declare const DiffMaxContext: number;
+/**
+ * Split text into logical lines. A trailing newline terminates the last line
+ * rather than creating an empty one; `\r` is stripped so CRLF files diff
+ * cleanly against LF content.
+ *
+ * @param text - Text to split.
+ * @returns Lines without terminators.
+ */
+export declare const splitDiffLines: (text: string) => string[];
+/**
+ * Build a diff source from caller-supplied text. The fingerprint covers the
+ * exact input, including its trailing newline.
+ *
+ * @param text - Whole text.
+ * @returns Source lines, fingerprint and truncation flag.
+ */
+export declare const textDiffSource: (text: string) => DiffSource;
+/**
+ * Diff two prepared sources. The fingerprints on the result always cover the
+ * whole input, even when the diff was truncated to `DiffMaxLines`.
+ *
+ * @param path - Root-relative path the result describes.
+ * @param before - Original side.
+ * @param after - New side.
+ * @param context - Unchanged lines retained on each side.
+ * @returns Diff result with counts and hunks.
+ */
+export declare const diffSources: (path: string, before: DiffSource, after: DiffSource, context?: number) => DiffResult;
+/**
+ * Diff two texts directly.
+ *
+ * @param path - Root-relative path the result describes.
+ * @param before - Original text.
+ * @param after - New text.
+ * @param options - Context size.
+ * @returns Diff result.
+ */
+export declare const diffText: (path: string, before: string, after: string, options?: DiffOptions) => DiffResult;