totemlayer 0.1.2 → 0.1.4

package/bin/repository.mjs

@@ -0,0 +1,135 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const runFile = promisify(execFile);
+const COMMIT = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i;
+
+export function repositoryIdFromRemote(remote) {
+  const value = remote.trim();
+  let host;
+  let path;
+  const scp = /^git@([^:]+):(.+)$/.exec(value);
+  if (scp) {
+    [, host, path] = scp;
+  } else {
+    let url;
+    try {
+      url = new URL(value);
+    } catch {
+      throw new Error("The Git origin must be a credential-free HTTPS or SSH remote.");
+    }
+    if (
+      !["https:", "ssh:"].includes(url.protocol) ||
+      url.password ||
+      (url.username && !(url.protocol === "ssh:" && url.username === "git")) ||
+      url.search ||
+      url.hash
+    )
+      throw new Error("The Git origin must be a credential-free HTTPS or SSH remote.");
+    host = url.host;
+    path = url.pathname.replace(/^\//, "");
+  }
+  path = path.replace(/\.git$/, "").replace(/\/$/, "");
+  if (
+    !host ||
+    !path ||
+    (!host.split(":")[0].includes(".") && host.split(":")[0] !== "localhost") ||
+    !path
+      .split("/")
+      .every((part) => part && part !== "." && part !== ".." && /^[a-zA-Z0-9._-]+$/.test(part))
+  )
+    throw new Error("The Git origin cannot be represented as a safe Totem repository ID.");
+  return `${host.toLowerCase()}/${path}`;
+}
+
+async function git(root, ...args) {
+  try {
+    const { stdout } = await runFile(
+      "git",
+      ["-c", "core.fsmonitor=false", "--no-optional-locks", "-C", root, ...args],
+      {
+        timeout: 10_000,
+        maxBuffer: 256 * 1024,
+        encoding: "utf8",
+      },
+    );
+    return args.includes("-z") ? stdout : stdout.trim();
+  } catch {
+    throw new Error("The configured local Git repository could not be inspected.");
+  }
+}
+
+function configuredRoot(environment = process.env) {
+  return environment.TOTEM_REPOSITORY_ROOT?.trim() || process.cwd();
+}
+
+export async function inspectLocalRepository(environment = process.env) {
+  const root = configuredRoot(environment);
+  const topLevel = await git(root, "rev-parse", "--show-toplevel");
+  const [remote, headCommit, currentBranch, status] = await Promise.all([
+    git(topLevel, "remote", "get-url", "origin"),
+    git(topLevel, "rev-parse", "HEAD"),
+    git(topLevel, "branch", "--show-current"),
+    git(topLevel, "status", "--porcelain=v1", "--untracked-files=normal"),
+  ]);
+  return {
+    repository: repositoryIdFromRemote(remote),
+    headCommit,
+    currentBranch: currentBranch || null,
+    clean: status.length === 0,
+  };
+}
+
+function withinScope(path, claimed) {
+  const normalized = path.normalize("NFC").toLowerCase();
+  return claimed.some((scope) => {
+    const base = scope.normalize("NFC").toLowerCase();
+    return normalized === base || normalized.startsWith(`${base}/`);
+  });
+}
+
+export async function verifyLocalRepoClaim(task, claim, environment = process.env) {
+  if (!COMMIT.test(task.baseCommit) || !COMMIT.test(claim.baseCommit))
+    throw new Error("The task needs full Git commit hashes.");
+  const local = await inspectLocalRepository(environment);
+  const root = await git(configuredRoot(environment), "rev-parse", "--show-toplevel");
+  const repositoryMatches =
+    local.repository === task.repository && claim.repository === task.repository;
+  const baseMatches = claim.baseCommit.toLowerCase() === task.baseCommit.toLowerCase();
+  const branchMatches = local.currentBranch === claim.branch;
+  const mergeBase = await git(root, "merge-base", task.baseCommit, "HEAD").catch(() => null);
+  const ancestryMatches = mergeBase?.toLowerCase() === task.baseCommit.toLowerCase();
+  const changed = ancestryMatches
+    ? (
+        await git(
+          root,
+          "diff",
+          "--no-ext-diff",
+          "--no-renames",
+          "--name-only",
+          "-z",
+          `${task.baseCommit}..HEAD`,
+        )
+      )
+        .split("\0")
+        .filter(Boolean)
+    : [];
+  const outOfScopePaths = changed.filter((path) => !withinScope(path, claim.paths));
+  return {
+    ...local,
+    repositoryMatches,
+    baseMatches,
+    branchMatches,
+    baseAncestor: ancestryMatches,
+    changedPaths: changed,
+    outOfScopePaths,
+    locallyVerified:
+      repositoryMatches &&
+      baseMatches &&
+      branchMatches &&
+      ancestryMatches &&
+      local.clean &&
+      outOfScopePaths.length === 0,
+    remotelyVerified: false,
+  };
+}

package/bin/sdk/errors.js

@@ -0,0 +1,54 @@
+export class TotemError extends Error {
+    code;
+    status;
+    requestId;
+    constructor(message, options) {
+        super(message, { cause: options.cause });
+        this.name = new.target.name;
+        this.code = options.code;
+        this.status = options.status;
+        this.requestId = options.requestId;
+    }
+}
+export class TotemAuthenticationError extends TotemError {
+}
+export class TotemPermissionError extends TotemError {
+}
+export class TotemNotFoundError extends TotemError {
+}
+export class TotemConflictError extends TotemError {
+}
+export class TotemRateLimitError extends TotemError {
+}
+export class TotemTimeoutError extends TotemError {
+}
+export class TotemNetworkError extends TotemError {
+}
+export class TotemCanceledError extends TotemError {
+}
+export function apiError(status, body, requestId) {
+    const error = body &&
+        typeof body === "object" &&
+        "error" in body &&
+        body.error &&
+        typeof body.error === "object"
+        ? body.error
+        : {};
+    const message = "message" in error && typeof error.message === "string"
+        ? error.message
+        : `Totem request failed (${status}).`;
+    const code = "code" in error && typeof error.code === "string" ? error.code : "HTTP_ERROR";
+    const id = "requestId" in error && typeof error.requestId === "string" ? error.requestId : requestId;
+    const Constructor = status === 401
+        ? TotemAuthenticationError
+        : status === 403
+            ? TotemPermissionError
+            : status === 404
+                ? TotemNotFoundError
+                : status === 409
+                    ? TotemConflictError
+                    : status === 429
+                        ? TotemRateLimitError
+                        : TotemError;
+    return new Constructor(message, { code, status, requestId: id });
+}

package/bin/sdk/index.js

@@ -0,0 +1,307 @@
+import { TotemError } from "./errors.js";
+import { idempotencyKey, sleep, Transport } from "./transport.js";
+export * from "./types.js";
+export * from "./errors.js";
+export { idempotencyKey } from "./transport.js";
+function content(input) {
+    // Runtime callers (including JavaScript) cannot accidentally provide a sender.
+    if ("from" in input)
+        throw new TotemError("Sender identity comes from the API key.", { code: "INVALID_MESSAGE" });
+    return input.content ?? { type: "text", text: input.text ?? input.message };
+}
+async function* paginate(fetchPage, cursor) {
+    const seen = new Set();
+    if (cursor)
+        seen.add(cursor);
+    do {
+        const page = await fetchPage(cursor);
+        for (const item of page.data)
+            yield item;
+        cursor = page.nextCursor ?? undefined;
+        if (cursor && seen.has(cursor))
+            throw new TotemError("Totem returned a repeated pagination cursor.", {
+                code: "INVALID_RESPONSE",
+            });
+        if (cursor)
+            seen.add(cursor);
+    } while (cursor);
+}
+export class Totem {
+    #transport;
+    #address;
+    constructor(options) {
+        this.#transport = new Transport(options);
+        this.#address = options.address?.trim().toLowerCase();
+    }
+    static async connect(options) {
+        return new Totem(options).connect();
+    }
+    async connect() {
+        const identity = await this.agent();
+        if (this.#address && this.#address !== identity.address.toLowerCase()) {
+            throw new TotemError("The configured address does not match the authenticated agent.", {
+                code: "IDENTITY_MISMATCH",
+            });
+        }
+        return new ConnectedAgent(this, identity);
+    }
+    async agent(options) {
+        return (await this.#transport.request("GET", "/agents/me", options)).data;
+    }
+    async resolve(address, options) {
+        return (await this.#transport.request("GET", `/resolve/${encodeURIComponent(address)}`, options)).data;
+    }
+    agents = {
+        search: (query = {}, options) => this.#transport.request("GET", "/agents/search", { ...options, query }),
+        iterate: (query = {}, options) => paginate((cursor) => this.agents.search({ ...query, cursor }, options), query.cursor),
+    };
+    attachments = {
+        upload: async (name, mediaType, bytes, options = {}) => {
+            if (!bytes.byteLength || bytes.byteLength > 2 * 1024 * 1024)
+                throw new TotemError("Attachments must be nonempty and no larger than 2 MiB.", {
+                    code: "ATTACHMENT_SIZE_INVALID",
+                });
+            return (await this.#transport.request("POST", "/attachments", {
+                ...options,
+                binaryBody: bytes,
+                headers: { "Content-Type": mediaType, "X-Totem-File-Name": encodeURIComponent(name) },
+            })).data;
+        },
+        download: (id, options) => this.#transport.download(`/attachments/${encodeURIComponent(id)}`, options),
+    };
+    messages = {
+        send: async (input, options = {}) => {
+            const body = { ...input, content: content(input) };
+            delete body.text;
+            delete body.message;
+            return (await this.#transport.request("POST", "/messages", {
+                ...options,
+                body,
+                idempotencyKey: options.idempotencyKey ?? idempotencyKey(),
+            })).data;
+        },
+        list: (query = {}, options) => this.#transport.request("GET", "/messages", { ...options, query }),
+        iterate: (query = {}, options) => paginate((cursor) => this.messages.list({ ...query, cursor }, options), query.cursor),
+        get: async (id, options) => (await this.#transport.request("GET", `/messages/${encodeURIComponent(id)}`, options)).data,
+        reply: async (id, text, options = {}) => (await this.#transport.request("POST", `/messages/${encodeURIComponent(id)}/reply`, {
+            ...options,
+            body: {
+                content: {
+                    type: "text",
+                    text,
+                    ...(options.attachments ? { attachments: options.attachments } : {}),
+                },
+                ...(options.metadata ? { metadata: options.metadata } : {}),
+            },
+            idempotencyKey: options.idempotencyKey ?? `sdk:reply:${id}`,
+        })).data,
+        ack: async (id, options) => (await this.#transport.request("POST", `/messages/${encodeURIComponent(id)}/ack`, {
+            ...options,
+            body: {},
+            retrySafe: true,
+        })).data,
+    };
+    send(input, textOrOptions, options) {
+        if (typeof input === "string")
+            return this.messages.send({ to: input, text: textOrOptions }, options);
+        return this.messages.send(input, textOrOptions);
+    }
+    conversations = {
+        create: async (input, options) => {
+            // Creation has no automatic retry until the server supports an idempotent contract.
+            const result = await this.#transport.request("POST", "/conversations", { ...options, body: input });
+            return new ConversationHandle(this, result.data, input.with);
+        },
+        list: (query = {}, options) => this.#transport.request("GET", "/conversations", { ...options, query }),
+        get: async (id, options) => (await this.#transport.request("GET", `/conversations/${encodeURIComponent(id)}`, options)).data,
+        messages: (id, query = {}, options) => this.#transport.request("GET", `/conversations/${encodeURIComponent(id)}/messages`, {
+            ...options,
+            query,
+        }),
+    };
+    startConversation(input, options) {
+        return this.conversations.create(input, options);
+    }
+    chats = {
+        list: (query = {}, options) => this.#transport.request("GET", "/chats", { ...options, query }),
+        get: async (id, options = {}) => (await this.#transport.request("GET", `/chats/${encodeURIComponent(id)}`, {
+            signal: options.signal,
+            query: { cursor: options.cursor, before: options.before, limit: options.limit },
+        })).data,
+        /** Publish as the authenticated agent; this never creates a human command. */
+        updates: async (id, text, options = {}) => (await this.#transport.request("POST", `/chats/${encodeURIComponent(id)}/updates`, {
+            ...options,
+            body: { text },
+            idempotencyKey: options.idempotencyKey ?? idempotencyKey(),
+        })).data,
+    };
+    chatCommands = {
+        list: (query = {}, options) => this.#transport.request("GET", "/chat-commands", { ...options, query }),
+        claim: async (id, options) => (await this.#transport.request("POST", `/chat-commands/${encodeURIComponent(id)}/claim`, { ...options, body: {} })).data,
+        renew: async (id, leaseToken, options) => (await this.#transport.request("POST", `/chat-commands/${encodeURIComponent(id)}/renew`, { ...options, body: { leaseToken }, retrySafe: true })).data,
+        complete: async (id, input, options = {}) => (await this.#transport.request("POST", `/chat-commands/${encodeURIComponent(id)}/complete`, { ...options, body: input, idempotencyKey: options.idempotencyKey ?? idempotencyKey() })).data,
+        fail: async (id, input, options) => (await this.#transport.request("POST", `/chat-commands/${encodeURIComponent(id)}/fail`, { ...options, body: input, retrySafe: true })).data,
+    };
+    runtime = {
+        heartbeat: async (input = {}, options) => (await this.#transport.request("POST", "/runtime/heartbeat", {
+            ...options,
+            body: input,
+            retrySafe: true,
+        })).data,
+    };
+    tasks = {
+        create: async (input, options = {}) => (await this.#transport.request("POST", "/tasks", {
+            ...options,
+            body: {
+                to: input.to,
+                content: content(input),
+                conversationId: input.conversationId,
+                metadata: input.metadata,
+                ttlSeconds: input.ttlSeconds,
+                authorization: input.authorization,
+            },
+            idempotencyKey: options.idempotencyKey ?? idempotencyKey(),
+        })).data,
+        get: async (id, options) => (await this.#transport.request("GET", `/tasks/${encodeURIComponent(id)}`, options)).data,
+        list: (query = {}, options) => this.#transport.request("GET", "/tasks", { ...options, query }),
+        iterate: (query = {}, options) => paginate((cursor) => this.tasks.list({ ...query, cursor }, options), query.cursor),
+        postUpdate: async (id, text, options = {}) => (await this.#transport.request("POST", `/tasks/${encodeURIComponent(id)}/messages`, {
+            ...options,
+            body: { content: { type: "text", text } },
+            idempotencyKey: options.idempotencyKey ?? idempotencyKey(),
+        })).data,
+        update: async (id, input, options) => (await this.#transport.request("PATCH", `/tasks/${encodeURIComponent(id)}`, {
+            ...options,
+            body: input,
+        })).data,
+        cancel: async (id, options) => (await this.#transport.request("POST", `/tasks/${encodeURIComponent(id)}/cancel`, { ...options, body: {} })).data,
+    };
+    repositories = {
+        getTask: async (taskId, options) => (await this.#transport.request("GET", `/tasks/${encodeURIComponent(taskId)}/repository`, options)).data,
+        claim: async (taskId, input, options) => (await this.#transport.request("POST", `/tasks/${encodeURIComponent(taskId)}/repository`, { ...options, body: input })).data,
+        update: async (taskId, input, options) => (await this.#transport.request("PATCH", `/tasks/${encodeURIComponent(taskId)}/repository`, { ...options, body: input })).data,
+    };
+    github = {
+        repositories: async (options) => (await this.#transport.request("GET", "/github/repositories", options)).data,
+        openPullRequest: async (taskId, input, options) => (await this.#transport.request("POST", `/github/pull-requests?taskId=${encodeURIComponent(taskId)}`, { ...options, body: input })).data,
+    };
+}
+export class ConversationHandle {
+    id;
+    conversation;
+    #totem;
+    #recipient;
+    constructor(totem, conversation, recipient) {
+        this.#totem = totem;
+        this.conversation = conversation;
+        this.id = conversation.id;
+        this.#recipient = recipient;
+    }
+    send(text, options) {
+        return this.#totem.messages.send({ to: this.#recipient, text, conversationId: this.id }, options);
+    }
+    messages(query = {}, options) {
+        return this.#totem.conversations.messages(this.id, query, options);
+    }
+}
+export class ConnectedAgent {
+    identity;
+    address;
+    client;
+    #subscription;
+    #lastError;
+    constructor(client, identity) {
+        this.client = client;
+        this.identity = identity;
+        this.address = identity.address;
+    }
+    get lastError() {
+        return this.#lastError;
+    }
+    send(input, textOrOptions, options) {
+        return typeof input === "string"
+            ? this.client.send(input, textOrOptions, options)
+            : this.client.send(input, textOrOptions);
+    }
+    startConversation(input) {
+        return this.client.startConversation(input);
+    }
+    on(event, handler, options = {}) {
+        if (event !== "message")
+            throw new TotemError("Only message subscriptions are supported.", { code: "INVALID_EVENT" });
+        if (this.#subscription)
+            throw new TotemError("This agent already has a message listener.", {
+                code: "ALREADY_LISTENING",
+            });
+        const interval = options.pollIntervalMs ?? 1000;
+        if (!Number.isFinite(interval) || interval < 10)
+            throw new TotemError("pollIntervalMs must be at least 10.", { code: "INVALID_CONFIG" });
+        const controller = new AbortController();
+        const report = (cause) => {
+            this.#lastError = cause instanceof Error ? cause : new Error(String(cause));
+            try {
+                options.onError?.(this.#lastError);
+            }
+            catch {
+                /* Error reporting cannot acknowledge an unprocessed message. */
+            }
+        };
+        const done = (async () => {
+            while (!controller.signal.aborted) {
+                try {
+                    for await (const message of this.client.messages.iterate({ direction: "inbound", unread: true, limit: 100 }, { signal: controller.signal })) {
+                        if (controller.signal.aborted)
+                            break;
+                        const incoming = {
+                            ...message,
+                            text: message.content.type === "text"
+                                ? message.content.text
+                                : JSON.stringify(message.content.data),
+                            reply: (text, writeOptions = {}) => this.client.messages.reply(message.id, text, {
+                                ...writeOptions,
+                                idempotencyKey: writeOptions.idempotencyKey ?? `reply:${message.id}:0`,
+                            }),
+                            ack: () => this.client.messages.ack(message.id),
+                        };
+                        try {
+                            await handler(incoming);
+                            await incoming.ack();
+                        }
+                        catch (error) {
+                            report(error);
+                        }
+                    }
+                }
+                catch (error) {
+                    if (!controller.signal.aborted)
+                        report(error);
+                }
+                if (!controller.signal.aborted) {
+                    try {
+                        await sleep(interval, controller.signal);
+                    }
+                    catch {
+                        /* stop wakes the poller. */
+                    }
+                }
+            }
+        })();
+        const subscription = {
+            done,
+            stop: async () => {
+                controller.abort();
+                await done;
+                if (this.#subscription === subscription)
+                    this.#subscription = undefined;
+            },
+        };
+        this.#subscription = subscription;
+        return subscription;
+    }
+    async stop() {
+        await this.#subscription?.stop();
+    }
+}
+/** Compatibility name for callers who prefer `new TotemAgent({ address, apiKey })`. */
+export class TotemAgent extends Totem {
+}