attention-manifest-protocol 0.4.2 → 0.4.3

package/src/process/process.ts

@@ -1,240 +0,0 @@
-/**
- * Process: a persistent agent.
- *
- * The process is the agent itself: it owns a budget, a memory (address space),
- * capabilities and a parent (for delegated sub-agents). It does not "complete";
- * it moves between created/running/idle/suspended/terminated while tasks come
- * and go. A task is a thread (see `src/thread`), so one agent does one thing at
- * a time, like a CPU running one thread.
- */
-import type { DatabaseSync } from "node:sqlite";
-
-import type { Budget, Id, Usage } from "../types/common.ts";
-import { isId } from "../boundary/ids.ts";
-import { KernelError } from "../error/kernelError.ts";
-import { putObject } from "../database/store/database.ts";
-import { requirePermission } from "../authz/authz.ts";
-import type { Subject } from "../authz/authz.ts";
-import { ExecutionRepository } from "../database/repository/executionRepository.ts";
-import { AddressSpaceRepository } from "../database/repository/addressSpaceRepository.ts";
-
-export { canProcessTransition } from "./transitions.ts";
-
-export type ProcessState = "created" | "running" | "idle" | "suspended" | "terminated";
-
-export interface ProcessSpec {
-    id: Id;
-    /**
-     * Display name of the agent.
-     */
-    name: string;
-    role?: string;
-    priority?: number;
-    budget?: Budget;
-    parentPid?: number;
-}
-
-export interface ProcessRecord {
-    pid: number;
-    id: Id;
-    name: string;
-    role?: string;
-    state: ProcessState;
-    priority: number;
-    budget: Budget;
-    used: Usage;
-    parentPid?: number;
-    createdAt: string;
-    startedAt?: string;
-    terminatedAt?: string;
-    exitCode?: string;
-    exitNote?: string;
-}
-
-export interface ProcessPatch {
-    startedAt?: string;
-    terminatedAt?: string;
-    exitCode?: string;
-    exitNote?: string;
-}
-
-type UsageTotals = Required<Pick<Usage, "tokens" | "ms" | "calls" | "interrupts" | "money">>;
-
-type ChargeResult = {
-    ok: boolean;
-    exceeded: string[];
-};
-
-type ProcessCreator = (db: DatabaseSync, spec: ProcessSpec, at: string) => ProcessRecord;
-
-type ProcessStates = ProcessState | ProcessState[];
-
-type ProcessTransition = (db: DatabaseSync, pid: number, from: ProcessStates, to: ProcessState, patch?: ProcessPatch) => ProcessRecord;
-
-type ChargeProcess = (db: DatabaseSync, pid: number, usage: Budget, at: string) => ChargeResult;
-
-type ProcessTerminator = (db: DatabaseSync, pid: number, note: string, at: string, code?: string) => ProcessRecord;
-
-type ObjectAttachment = (db: DatabaseSync, pid: number, seq: number, role: AddressRole, mode: AddressMode, at: string, subject?: Subject) => void;
-
-type ProcessObjectReader = (db: DatabaseSync, pid: number, seq: number, subject: Subject, at: string) => ProcessObjectRecord;
-
-type ProcessForker = (db: DatabaseSync, parentPid: number, spec: ProcessSpec, at: string, subject?: Subject) => ProcessRecord;
-
-type ProcessJoiner = (db: DatabaseSync, childPid: number, parentPid: number, at: string, subject?: Subject) => number;
-
-type ObjectPlacement = {
-    seq: number;
-    hash: string;
-};
-
-type ObjectPutter = (db: DatabaseSync, kind: string, id: Id, body: unknown, at: string) => ObjectPlacement;
-
-/**
- * Agent lifecycle. `terminated` has no outgoing edge.
- */
-export const emptyUsage: () => UsageTotals = (): UsageTotals => ({
-    tokens: 0,
-    ms: 0,
-    calls: 0,
-    interrupts: 0,
-    money: 0,
-});
-
-export const createProcess: ProcessCreator = (db: DatabaseSync, spec: ProcessSpec, at: string): ProcessRecord => {
-    if (!isId(spec.id)) {
-        throw new KernelError("invalid_process", [`id ${spec.id} is not a valid AMP id`]);
-    }
-    if (spec.name.trim().length === 0) {
-        throw new KernelError("invalid_process", ["name is empty"]);
-    }
-    return new ExecutionRepository(db).createAgent(spec, at);
-};
-
-export const findProcess: (db: DatabaseSync, id: Id) => ProcessRecord | undefined = (db: DatabaseSync, id: Id): ProcessRecord | undefined =>
-    new ExecutionRepository(db).findAgentByExternalId(id);
-
-export const getProcess: (db: DatabaseSync, pid: number) => ProcessRecord = (db: DatabaseSync, pid: number): ProcessRecord =>
-    new ExecutionRepository(db).getAgent(pid);
-
-export const listProcesses: (db: DatabaseSync, state?: ProcessState) => ProcessRecord[] = (db: DatabaseSync, state?: ProcessState): ProcessRecord[] =>
-    new ExecutionRepository(db).listAgents(state);
-
-/**
- * Guarded agent transition. The update only applies from one of `from`.
- */
-export const transitionProcess: ProcessTransition = (db: DatabaseSync, pid: number, from: ProcessStates, to: ProcessState, patch: ProcessPatch = {}) =>
-    new ExecutionRepository(db).transitionAgent(pid, from, to, patch);
-
-/**
- * Charge the agent's overall budget. Exhaustion suspends the agent (it can be
- * resumed with a larger budget); it does not silently drop the task.
- */
-export const chargeProcess: ChargeProcess = (db: DatabaseSync, pid: number, usage: Budget, at: string): ChargeResult =>
-    new ExecutionRepository(db).chargeAgent(pid, usage, at);
-
-export const terminateProcess: ProcessTerminator = (db: DatabaseSync, pid: number, note: string, at: string, code: string = "TERMINATED"): ProcessRecord => {
-    return transitionProcess(db, pid, ["created", "running", "idle", "suspended"], "terminated", { terminatedAt: at, exitCode: code, exitNote: note });
-};
-
-/**
- * ----------------------------- address space -----------------------------
- */
-
-export type AddressRole = "own" | "inherited" | "mapped" | "joined";
-export type AddressMode = "read" | "write";
-
-export interface ProcessObjectRecord {
-    seq: number;
-    kind: string;
-    id: string;
-    body: string;
-    role: AddressRole;
-    mode: AddressMode;
-}
-
-/**
- * Map an immutable object into an agent's memory.
- *
- * `own` is writable, `inherited` is the read-only copy-on-write view a fork
- * gets, `mapped`/`joined` are cross-agent views. Mapped reads need a capability
- * unless the caller is the owner.
- */
-export const attachObject: ObjectAttachment = (
-    db: DatabaseSync,
-    pid: number,
-    seq: number,
-    role: AddressRole,
-    mode: AddressMode,
-    at: string,
-    subject?: Subject,
-) => {
-    getProcess(db, pid);
-    const address: AddressSpaceRepository = new AddressSpaceRepository(db);
-    if (!address.hasObject(seq)) {
-        throw new KernelError("unknown_object", [`seq ${seq} is not in the object store`]);
-    }
-    if (subject !== (void 0)) {
-        requirePermission(db, subject, mode === "write" ? "write" : "read", { kind: "object", id: `${seq}`, ownerPid: pid }, at);
-    }
-    address.attach(pid, seq, role, mode, at);
-};
-
-export const processObjects: (db: DatabaseSync, pid: number) => ProcessObjectRecord[] = (db: DatabaseSync, pid: number): ProcessObjectRecord[] =>
-    new AddressSpaceRepository(db).list(pid);
-
-export const readProcessObject: ProcessObjectReader = (db: DatabaseSync, pid: number, seq: number, subject: Subject, at: string): ProcessObjectRecord => {
-    const row: ProcessObjectRecord | undefined = new AddressSpaceRepository(db).read(pid, seq);
-    if (row === (void 0)) {
-        throw new KernelError("unknown_object", [`seq ${seq} is not mapped into pid ${pid}`]);
-    }
-    if (row.role === "own" || row.role === "inherited" || row.role === "joined") {
-        return row;
-    }
-    requirePermission(db, subject, "read", { kind: "object", id: `${seq}` }, at);
-    return row;
-};
-
-export const writeProcessObject: ProcessObjectReader = (db: DatabaseSync, pid: number, seq: number, subject: Subject, at: string): ProcessObjectRecord => {
-    const row: ProcessObjectRecord = readProcessObject(db, pid, seq, subject, at);
-    if (row.mode !== "write") {
-        requirePermission(db, subject, "write", { kind: "object", id: `${seq}` }, at);
-    }
-    return row;
-};
-
-/**
- * Fork a delegated sub-agent with a read-only view of the parent's memory.
- */
-export const forkProcess: ProcessForker = (db: DatabaseSync, parentPid: number, spec: ProcessSpec, at: string, subject?: Subject): ProcessRecord => {
-    const parent: ProcessRecord = getProcess(db, parentPid);
-    if (subject !== (void 0)) {
-        requirePermission(db, subject, "fork", { kind: "process", id: parent.id, ownerPid: parentPid }, at);
-    }
-    const child: ProcessRecord = createProcess(db, { ...spec, parentPid }, at);
-    new AddressSpaceRepository(db).fork(parentPid, child.pid, at);
-    return child;
-};
-
-/**
- * Join a sub-agent back: its own objects become read-only pages in the parent.
- */
-export const joinProcess: ProcessJoiner = (db: DatabaseSync, childPid: number, parentPid: number, at: string, subject?: Subject): number => {
-    const child: ProcessRecord = getProcess(db, childPid);
-    if (child.parentPid !== parentPid) {
-        throw new KernelError("invalid_transition", [`pid ${childPid} is not a child of ${parentPid}`]);
-    }
-    if (subject !== (void 0)) {
-        requirePermission(db, subject, "join", { kind: "process", id: child.id, ownerPid: parentPid }, at);
-    }
-    const result: number = new AddressSpaceRepository(db).join(parentPid, childPid, at);
-    terminateProcess(db, childPid, `joined into ${parentPid}`, at, "JOINED");
-    return result;
-};
-
-/**
- * Append a claim/event/frame object inside the same transaction as the step.
- */
-export const putProcessObject: ObjectPutter = (db: DatabaseSync, kind: string, id: Id, body: unknown, at: string): ObjectPlacement => {
-    return putObject(db, kind, id, body, at);
-};

package/src/process/transitions.ts

@@ -1,19 +0,0 @@
-/**
- * Pure process lifecycle predicate; no DB or domain implementation imports.
- */
-import type { ProcessState } from "./process.ts";
-
-export const ProcessEdges: Record<ProcessState, readonly ProcessState[]> = {
-    created: ["running", "idle", "suspended", "terminated"],
-    running: ["idle", "suspended", "terminated"],
-    idle: ["running", "suspended", "terminated"],
-    suspended: ["running", "idle", "terminated"],
-    terminated: [],
-};
-
-/**
- * Predicate deciding whether one process state may move to another.
- */
-type ProcessTransitionPredicate = (from: ProcessState, to: ProcessState) => boolean;
-
-export const canProcessTransition: ProcessTransitionPredicate = (from: ProcessState, to: ProcessState): boolean => ProcessEdges[from].includes(to);

package/src/progress/index.ts

@@ -1,2 +0,0 @@
-export { checkpointProgress, computeProgress } from "./progress.ts";
-export type { ProgressSnapshot } from "./progress.ts";

package/src/progress/progress.ts

@@ -1,85 +0,0 @@
-/**
- * Progress: a read-only projection of a process's threads and steps.
- *
- * It is computed from the store, never self-reported. `checkpoint` appends a
- * `progress` object so a supervisor can compare a later view with the committed
- * one instead of trusting the in-memory counter.
- */
-import type { DatabaseSync } from "node:sqlite";
-
-import { putObject } from "../database/store/database.ts";
-
-type ProcessRow = {
-    state: string;
-    used: string;
-};
-
-type ThreadStateRow = {
-    state: string;
-    n: number;
-};
-
-type CountRow = {
-    n: number;
-};
-
-type UsageRow = {
-    tokens?: number;
-};
-
-export interface ProgressSnapshot {
-    pid: number;
-    state: string;
-    totalThreads: number;
-    doneThreads: number;
-    failedThreads: number;
-    steps: number;
-    tokens: number;
-    percent: number;
-    checkpoint?: string;
-}
-
-export const computeProgress: (db: DatabaseSync, pid: number) => ProgressSnapshot = (db: DatabaseSync, pid: number): ProgressSnapshot => {
-    const process: ProcessRow | undefined = db.prepare("SELECT state, used FROM processes WHERE pid = ?").get(pid) as ProcessRow | undefined;
-    if (process === (void 0)) {
-        throw new Error(`unknown process ${pid}`);
-    }
-    const threads: ThreadStateRow[] = db.prepare("SELECT state, COUNT(*) AS n FROM threads WHERE pid = ? GROUP BY state").all(pid) as ThreadStateRow[];
-    const stepRow: CountRow = db.prepare("SELECT COUNT(*) AS n FROM steps WHERE pid = ?").get(pid) as CountRow;
-    let total: number = 0;
-    let done: number = 0;
-    let failed: number = 0;
-    for (let index: number = 0; index < threads.length; index += 1) {
-        const row: ThreadStateRow = threads[index];
-        total += row.n;
-        if (row.state === "done") {
-            done += row.n;
-        }
-        if (row.state === "failed") {
-            failed += row.n;
-        }
-    }
-    const used: UsageRow = JSON.parse(process.used) as UsageRow;
-    return {
-        pid,
-        state: process.state,
-        totalThreads: total,
-        doneThreads: done,
-        failedThreads: failed,
-        steps: stepRow.n,
-        tokens: used.tokens ?? 0,
-        percent: total === 0 ? 0 : Math.round((done / total) * 1000) / 10,
-    };
-};
-
-type ProgressCheckpoint = (db: DatabaseSync, pid: number, at: string) => ProgressSnapshot;
-
-/**
- * Append the current view as an immutable `progress` object.
- */
-export const checkpointProgress: ProgressCheckpoint = (db: DatabaseSync, pid: number, at: string): ProgressSnapshot => {
-    const snapshot: ProgressSnapshot = computeProgress(db, pid);
-    const id: string = `pg.${pid}.${snapshot.steps}`;
-    putObject(db, "progress", id, { amp: "0.1", kind: "progress", id, at, ...snapshot }, at);
-    return { ...snapshot, checkpoint: id };
-};

package/src/protocol/a2a.ts

@@ -1,120 +0,0 @@
-import type { DelegationDoc } from "../cooperation/collaboration.ts";
-import { digestOf } from "../semantic/canonical.ts";
-import type { Channel, ChannelVerdict } from "./channel.ts";
-
-/**
- * A2A v1.0 Message. Part kinds are text | file | data.
- */
-export interface A2APart {
-    kind: "text" | "data";
-    text?: string;
-    data?: Record<string, unknown>;
-}
-
-export interface A2AMessage {
-    kind: "message";
-    messageId: string;
-    role: "user" | "agent";
-    parts: A2APart[];
-    metadata?: Record<string, unknown>;
-}
-
-export interface A2ARequest {
-    jsonrpc: "2.0";
-    id: string;
-    method: "message/send";
-    params: { message: A2AMessage };
-}
-
-export interface A2AChannelOptions {
-    url: string;
-    headers?: Record<string, string>;
-    timeoutMs?: number;
-}
-
-/**
- * Real A2A v1.0 binding: JSON-RPC `message/send` carrying an A2A Message.
- * The delegation rides in a `data` part plus metadata; a text part keeps the
- * request readable to a peer that does not know AMP yet.
- */
-export function toA2ARequest(doc: DelegationDoc): A2ARequest {
-    const message: A2AMessage = {
-        kind: "message",
-        messageId: doc.id,
-        role: "user",
-        parts: [
-            { kind: "text", text: `AMP delegation ${doc.id}: ${doc.granter} -> ${doc.delegatee} (depth ${doc.depth})` },
-            { kind: "data", data: { "io.amp/delegation": doc } },
-        ],
-        metadata: { "io.amp/delegation_digest": digestOf(doc), "io.amp/version": "0.1" },
-    };
-    return { jsonrpc: "2.0", id: `amp-${doc.id}`, method: "message/send", params: { message } };
-}
-
-/**
- * Closes the loop: use the endpoint the Agent Card advertised, not a hardcoded URL.
- */
-export function channelFromCard(card: { ok: boolean; endpoint?: string }, options: Omit<A2AChannelOptions, "url"> = {}): A2AChannel {
-    if (!card.ok || !card.endpoint) {
-        throw new Error("agent card has no usable endpoint");
-    }
-    return new A2AChannel({ url: card.endpoint, ...options });
-}
-
-export class A2AChannel implements Channel {
-    readonly url: string;
-    readonly extraHeaders: Record<string, string>;
-    readonly timeoutMs: number;
-    readonly requests: A2ARequest[] = [];
-
-    constructor(options: A2AChannelOptions) {
-        this.url = options.url;
-        this.extraHeaders = options.headers ?? {};
-        this.timeoutMs = options.timeoutMs ?? 5_000;
-    }
-
-    async send(doc: DelegationDoc): Promise<ChannelVerdict> {
-        const request = toA2ARequest(doc);
-        this.requests.push(request);
-
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
-        try {
-            const response = await fetch(this.url, {
-                method: "POST",
-                headers: {
-                    "content-type": "application/json",
-                    "a2a-version": "1.0",
-                    ...this.extraHeaders,
-                },
-                body: JSON.stringify(request),
-                signal: controller.signal,
-            });
-            if (!response.ok) {
-                return { accepted: false, reason: `HTTP ${response.status}` };
-            }
-
-            const body = (await response.json()) as {
-                error?: { code: number; message: string };
-                result?: { kind?: string; id?: string; status?: { state?: string } };
-            };
-            if (body.error) {
-                return { accepted: false, reason: `A2A ${body.error.code}: ${body.error.message}` };
-            }
-
-            const result = body.result;
-            if (result?.kind === "task") {
-                return { accepted: true, reason: `task ${result.id ?? ""} ${result.status?.state ?? "submitted"}` };
-            }
-            if (result?.kind === "message") {
-                return { accepted: true, reason: "agent replied with a message" };
-            }
-            return { accepted: false, reason: "unrecognised A2A result" };
-        } catch (error) {
-            const reason = error instanceof Error && error.name === "AbortError" ? "timeout" : `${error}`;
-            return { accepted: false, reason };
-        } finally {
-            clearTimeout(timer);
-        }
-    }
-}

package/src/protocol/channel.ts

@@ -1,44 +0,0 @@
-import type { DelegationDoc } from "../cooperation/collaboration.ts";
-import type { Delegation } from "../delegate/team.ts";
-import { toDelegationDoc } from "./wire.ts";
-
-export interface ChannelVerdict {
-    accepted: boolean;
-    reason?: string;
-}
-
-export interface Channel {
-    send(doc: DelegationDoc): Promise<ChannelVerdict>;
-}
-
-/**
- * Loopback channel: the peer is a policy function, not a promise.
- * It exists so the transport seam is testable before any network code lands.
- */
-export class LoopbackChannel implements Channel {
-    readonly sent: DelegationDoc[] = [];
-    private readonly policy: (doc: DelegationDoc) => ChannelVerdict;
-
-    constructor(policy: (doc: DelegationDoc) => ChannelVerdict = () => ({ accepted: true })) {
-        this.policy = policy;
-    }
-
-    async send(doc: DelegationDoc): Promise<ChannelVerdict> {
-        this.sent.push(doc);
-        return this.policy(doc);
-    }
-}
-
-type DelegateOver = (channel: Channel, delegation: Delegation) => Promise<DelegationDoc>;
-
-/**
- * Sends one delegation and fails closed if the peer declines it.
- */
-export const delegateOver: DelegateOver = async (channel: Channel, delegation: Delegation): Promise<DelegationDoc> => {
-    const doc: DelegationDoc = toDelegationDoc(delegation);
-    const verdict: ChannelVerdict = await channel.send(doc);
-    if (!verdict.accepted) {
-        throw new Error(`delegation rejected: ${verdict.reason ?? "no reason given"}`);
-    }
-    return doc;
-};