assent-cli 0.0.0-stage → 0.6.0

package/dist/client.d.ts

@@ -0,0 +1,224 @@
+import { CliConfig } from "./config";
+export interface FetchInit {
+    method: string;
+    headers: Record<string, string>;
+    body?: string | Uint8Array;
+    signal: AbortSignal;
+    redirect: "error";
+}
+export interface FetchResponse {
+    status: number;
+    text(): Promise<string>;
+}
+export type FetchLike = (url: string, init: FetchInit) => Promise<FetchResponse>;
+export interface HttpOptions {
+    apiUrl: string;
+    timeoutMs: number;
+    headers: Record<string, string>;
+}
+export declare const defaultFetch: FetchLike;
+export declare class HttpClient {
+    private readonly options;
+    private readonly fetchImpl;
+    constructor(options: HttpOptions, fetchImpl?: FetchLike);
+    request<T>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+    upload<T>(path: string, bytes: Uint8Array): Promise<T>;
+    private exchange;
+}
+export interface TaskView {
+    uuid: string;
+    status: string;
+    kind: string;
+    title: string;
+    answer: unknown;
+    answerExpiresAt: string | null;
+    heldItemIds?: string[];
+    withdrawnItemIds?: string[];
+    itemOutcomes?: Array<{
+        itemId: string;
+        outcome: string;
+    }> | null;
+    [key: string]: unknown;
+}
+export interface AttachmentView {
+    uuid: string;
+    name: string;
+    mime: string;
+    sizeBytes: number;
+    pages?: number;
+}
+export type LockResult = {
+    acquired: true;
+    token: string;
+    expiresAt: string;
+} | {
+    acquired: false;
+    heldByAgentUuid: string | null;
+    expiresAt: string;
+};
+export interface AskBody {
+    kind: string;
+    title: string;
+    detail?: string;
+    draft?: string;
+    url?: string;
+    actions?: Array<{
+        id: string;
+        label: string;
+        style?: string;
+    }>;
+    items?: Array<Record<string, unknown>>;
+    why?: string;
+    fields?: Array<Record<string, unknown>>;
+    group?: {
+        key: string;
+        title: string;
+    };
+    rules?: {
+        conflictOn?: string[];
+        totalOf?: string;
+        declineAction?: string;
+    };
+    dueAt?: string;
+    remindAt?: string;
+    dedupeKey?: string;
+    runUuid?: string;
+    question?: string;
+    answerType?: string;
+    effortMinutes?: number;
+    seriesKey?: string;
+    allowDuplicate?: boolean;
+    action?: string;
+    target?: string;
+    parentTaskUuid?: string;
+    parentItemId?: string;
+}
+export interface RuleCheck {
+    decision: string;
+    ruleUuid: string | null;
+    label: string | null;
+    reason: string | null;
+}
+export interface RuleView {
+    uuid: string;
+    effect: string;
+    action: string;
+    target: string | null;
+    label: string;
+    [key: string]: unknown;
+}
+export declare class AgentApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    static fromConfig(config: CliConfig, fetchImpl?: FetchLike): AgentApi;
+    me(): Promise<Record<string, unknown>>;
+    runStart(body: {
+        summary?: string;
+        maxMinutes?: number;
+    }): Promise<{
+        uuid: string;
+    }>;
+    runFinish(uuid: string, body: {
+        status: string;
+        retryAt?: string;
+        issue?: {
+            reason: string;
+            impact: string;
+            action: string;
+        };
+        exitCode?: number;
+        summary?: string;
+        logTail?: string;
+        taskUuid?: string;
+        results?: Record<string, number>;
+    }): Promise<Record<string, unknown>>;
+    runDefer(uuid: string, body: {
+        retryAt: string;
+    }): Promise<Record<string, unknown>>;
+    runProgress(uuid: string, body: {
+        done: number;
+        total: number;
+        label?: string;
+    }): Promise<Record<string, unknown>>;
+    taskUpdate(uuid: string, body: {
+        dueAt?: string | null;
+        remindAt?: string | null;
+    }): Promise<TaskView>;
+    ask(body: AskBody, idempotencyKey?: string): Promise<TaskView>;
+    resolve(uuid: string, body: {
+        outcome: "resolved" | "withdrawn";
+        note?: string;
+    }): Promise<TaskView>;
+    task(uuid: string): Promise<TaskView>;
+    itemResult(uuid: string, itemId: string, body: {
+        outcome: string;
+        reason?: string;
+        url?: string;
+    }): Promise<Record<string, unknown>>;
+    answers(): Promise<TaskView[]>;
+    pickedUp(uuid: string): Promise<TaskView>;
+    note(body: {
+        title: string;
+        content: string;
+        tags?: string[];
+        runUuid?: string;
+    }): Promise<Record<string, unknown>>;
+    noteUpdate(uuid: string, body: {
+        title?: string;
+        content?: string;
+        tags?: string[];
+    }): Promise<Record<string, unknown>>;
+    link(body: {
+        from: {
+            type: string;
+            uuid: string;
+        };
+        to: {
+            type: string;
+            uuid: string;
+        };
+        relation: string;
+    }): Promise<Record<string, unknown>>;
+    memory(): Promise<Record<string, unknown>[]>;
+    lockAcquire(body: {
+        resource: string;
+        ttlMinutes: number;
+    }): Promise<LockResult>;
+    lockRelease(body: {
+        resource: string;
+        token: string;
+    }): Promise<{
+        released: boolean;
+    }>;
+    handoff(body: {
+        toAgentName?: string;
+        toAgentUuid?: string;
+        title: string;
+        detail?: string;
+        runUuid?: string;
+    }): Promise<TaskView>;
+    handoffs(): Promise<TaskView[]>;
+    planCreate(body: Record<string, unknown>, idempotencyKey: string): Promise<Record<string, unknown>>;
+    projectGet(uuid: string): Promise<Record<string, unknown>>;
+    projectOverview(uuid: string): Promise<Record<string, unknown>>;
+    planGet(uuid: string): Promise<Record<string, unknown>>;
+    planSessions(uuid: string, body: Record<string, unknown>): Promise<{
+        updated: number;
+    }>;
+    attach(name: string, bytes: Uint8Array): Promise<AttachmentView>;
+    rulesCheck(body: {
+        action: string;
+        target?: string;
+        summary?: string;
+    }): Promise<RuleCheck>;
+    rulesList(): Promise<RuleView[]>;
+    rulesAdd(body: {
+        effect: "deny";
+        action: string;
+        target?: string;
+        reason?: string;
+        expiresIn: string;
+    }): Promise<RuleView>;
+    rulesRemove(uuid: string): Promise<RuleView>;
+    completeTask(uuid: string): Promise<TaskView>;
+}

package/dist/client.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentApi = exports.HttpClient = exports.defaultFetch = void 0;
+const exit_codes_1 = require("./exit-codes");
+const API_VERSION_SUFFIX = /\/api\/v1$/;
+const defaultFetch = (url, init) => fetch(url, init);
+exports.defaultFetch = defaultFetch;
+function parseBody(text) {
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function errorMessage(body, status) {
+    if (body && typeof body === "object" && "message" in body) {
+        const message = body.message;
+        if (Array.isArray(message))
+            return message.join("; ");
+        if (typeof message === "string")
+            return message;
+    }
+    return typeof body === "string" ? body.slice(0, 300) : `HTTP ${status}`;
+}
+class HttpClient {
+    options;
+    fetchImpl;
+    constructor(options, fetchImpl = exports.defaultFetch) {
+        this.options = options;
+        this.fetchImpl = fetchImpl;
+    }
+    request(method, path, body, extraHeaders = {}) {
+        return this.exchange(method, path, body === undefined ? undefined : JSON.stringify(body), extraHeaders);
+    }
+    upload(path, bytes) {
+        return this.exchange("POST", path, bytes, { "content-type": "application/octet-stream" });
+    }
+    async exchange(method, path, body, extraHeaders) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.options.timeoutMs);
+        let response;
+        let text;
+        try {
+            response = await this.fetchImpl(`${this.options.apiUrl.replace(API_VERSION_SUFFIX, "")}/api/v1${path}`, {
+                method,
+                headers: { accept: "application/json", "content-type": "application/json", ...this.options.headers, ...extraHeaders },
+                body,
+                signal: controller.signal,
+                redirect: "error",
+            });
+            text = await response.text();
+        }
+        catch (err) {
+            throw new exit_codes_1.CliError(exit_codes_1.EXIT.unreachable, `Assent is unreachable at ${this.options.apiUrl}: ${err.message}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const parsed = parseBody(text);
+        if (response.status >= 500 || response.status === 429)
+            throw new exit_codes_1.CliError(exit_codes_1.EXIT.unreachable, `Assent returned ${response.status}: ${errorMessage(parsed, response.status)}`, response.status);
+        if (response.status >= 400)
+            throw new exit_codes_1.CliError((0, exit_codes_1.exitCodeForStatus)(response.status), errorMessage(parsed, response.status), response.status);
+        return parsed;
+    }
+}
+exports.HttpClient = HttpClient;
+const segment = (value) => encodeURIComponent(value);
+class AgentApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    static fromConfig(config, fetchImpl) {
+        return new AgentApi(new HttpClient({ apiUrl: config.apiUrl, timeoutMs: config.timeoutMs, headers: { "x-ordia-agent-key": config.agentKey } }, fetchImpl));
+    }
+    me() { return this.http.request("GET", "/agent/me"); }
+    runStart(body) { return this.http.request("POST", "/agent/runs", body); }
+    runFinish(uuid, body) { return this.http.request("POST", `/agent/runs/${segment(uuid)}/finish`, body); }
+    runDefer(uuid, body) { return this.http.request("POST", `/agent/runs/${segment(uuid)}/defer`, body); }
+    runProgress(uuid, body) { return this.http.request("POST", `/agent/runs/${segment(uuid)}/progress`, body); }
+    taskUpdate(uuid, body) { return this.http.request("PATCH", `/agent/tasks/${segment(uuid)}`, body); }
+    ask(body, idempotencyKey) { return this.http.request("POST", "/agent/ask", body, idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}); }
+    resolve(uuid, body) { return this.http.request("POST", `/agent/tasks/${segment(uuid)}/resolve`, body); }
+    task(uuid) { return this.http.request("GET", `/agent/tasks/${segment(uuid)}`); }
+    itemResult(uuid, itemId, body) { return this.http.request("POST", `/agent/tasks/${segment(uuid)}/items/${segment(itemId)}/result`, body); }
+    answers() { return this.http.request("GET", "/agent/answers"); }
+    pickedUp(uuid) { return this.http.request("POST", `/agent/tasks/${segment(uuid)}/picked-up`); }
+    note(body) { return this.http.request("POST", "/agent/notes", body); }
+    noteUpdate(uuid, body) { return this.http.request("PATCH", `/agent/notes/${segment(uuid)}`, body); }
+    link(body) { return this.http.request("POST", "/agent/links", body); }
+    memory() { return this.http.request("GET", "/agent/memory"); }
+    lockAcquire(body) { return this.http.request("POST", "/agent/locks/acquire", body); }
+    lockRelease(body) { return this.http.request("POST", "/agent/locks/release", body); }
+    handoff(body) { return this.http.request("POST", "/agent/handoff", body); }
+    handoffs() { return this.http.request("GET", "/agent/handoffs"); }
+    planCreate(body, idempotencyKey) { return this.http.request("POST", "/agent/plans", body, { "Idempotency-Key": idempotencyKey }); }
+    projectGet(uuid) { return this.http.request("GET", `/agent/projects/${segment(uuid)}`); }
+    projectOverview(uuid) { return this.http.request("GET", `/agent/projects/${segment(uuid)}/overview`); }
+    planGet(uuid) { return this.http.request("GET", `/agent/plans/${segment(uuid)}`); }
+    planSessions(uuid, body) { return this.http.request("PATCH", `/agent/plans/${segment(uuid)}/sessions`, body); }
+    attach(name, bytes) { return this.http.upload(`/agent/attachments?name=${encodeURIComponent(name)}`, bytes); }
+    rulesCheck(body) { return this.http.request("POST", "/agent/rules/check", body); }
+    rulesList() { return this.http.request("GET", "/agent/rules"); }
+    rulesAdd(body) { return this.http.request("POST", "/agent/rules", body); }
+    rulesRemove(uuid) { return this.http.request("DELETE", `/agent/rules/${segment(uuid)}`); }
+    completeTask(uuid) { return this.http.request("POST", `/agent/tasks/${segment(uuid)}/complete`); }
+}
+exports.AgentApi = AgentApi;

package/dist/config.d.ts

@@ -0,0 +1,20 @@
+export interface CliConfig {
+    apiUrl: string;
+    agentKey: string;
+    timeoutMs: number;
+}
+export interface ConfigSources {
+    env: NodeJS.ProcessEnv;
+    home: string;
+    readFile(path: string): string | null;
+    exists(path: string): boolean;
+}
+export declare const DEFAULT_API_URL = "https://ordia-api.specvista.com/api/v1";
+export declare function assentEnv(env: NodeJS.ProcessEnv, name: string): string | undefined;
+export declare function configPath(env: NodeJS.ProcessEnv, home: string, exists: (path: string) => boolean): string;
+export declare function readConfigFile(src: ConfigSources): Record<string, unknown>;
+export declare function assertSecureApiUrl(apiUrl: string): void;
+export declare function loadCliConfig(src: ConfigSources): CliConfig;
+export declare function readFileOrNull(path: string): string | null;
+export declare function readBytesOrNull(path: string): Uint8Array | null;
+export declare function writeFileAtomic(path: string, content: string): void;

package/dist/config.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_API_URL = void 0;
+exports.assentEnv = assentEnv;
+exports.configPath = configPath;
+exports.readConfigFile = readConfigFile;
+exports.assertSecureApiUrl = assertSecureApiUrl;
+exports.loadCliConfig = loadCliConfig;
+exports.readFileOrNull = readFileOrNull;
+exports.readBytesOrNull = readBytesOrNull;
+exports.writeFileAtomic = writeFileAtomic;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const exit_codes_1 = require("./exit-codes");
+exports.DEFAULT_API_URL = "https://ordia-api.specvista.com/api/v1";
+const DEFAULT_TIMEOUT_MS = 10000;
+function assentEnv(env, name) {
+    return env[`ASSENT_${name}`] || env[`ORDIA_${name}`] || undefined;
+}
+function configPath(env, home, exists) {
+    const named = assentEnv(env, "CONFIG");
+    if (named)
+        return named;
+    const assentFile = (0, node_path_1.join)(home, ".assent", "config.json");
+    return exists(assentFile) ? assentFile : (0, node_path_1.join)(home, ".ordia", "config.json");
+}
+function readConfigFile(src) {
+    const path = configPath(src.env, src.home, src.exists);
+    const raw = src.readFile(path);
+    if (raw === null)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.auth, `${path} is not valid JSON`);
+    }
+    return parsed !== null && typeof parsed === "object" ? parsed : {};
+}
+function stringField(file, name) {
+    const value = file[name];
+    return typeof value === "string" ? value : "";
+}
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+function assertSecureApiUrl(apiUrl) {
+    let url;
+    try {
+        url = new URL(apiUrl);
+    }
+    catch {
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.auth, `The Assent API URL is not a valid URL: ${apiUrl}`);
+    }
+    if (url.protocol === "https:" || (url.protocol === "http:" && LOCAL_HOSTS.has(url.hostname)))
+        return;
+    throw new exit_codes_1.CliError(exit_codes_1.EXIT.auth, `The Assent API URL must use https (plain http only for localhost), so the agent key is never sent in the clear: ${apiUrl}`);
+}
+function loadCliConfig(src) {
+    const file = readConfigFile(src);
+    const apiUrl = (assentEnv(src.env, "API_URL") || stringField(file, "apiUrl") || exports.DEFAULT_API_URL).replace(/\/+$/, "");
+    assertSecureApiUrl(apiUrl);
+    const agentKey = assentEnv(src.env, "AGENT_KEY") || stringField(file, "agentKey");
+    if (!agentKey.startsWith("oak_"))
+        throw new exit_codes_1.CliError(exit_codes_1.EXIT.auth, "Not configured: set ASSENT_AGENT_KEY to an oak_ key, or agentKey in ~/.assent/config.json");
+    const timeoutMs = Number(assentEnv(src.env, "TIMEOUT_MS"));
+    return { apiUrl, agentKey, timeoutMs: Number.isInteger(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS };
+}
+function readFileOrNull(path) {
+    try {
+        return (0, node_fs_1.readFileSync)(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function readBytesOrNull(path) {
+    try {
+        return (0, node_fs_1.readFileSync)(path);
+    }
+    catch {
+        return null;
+    }
+}
+function writeFileAtomic(path, content) {
+    const target = (0, node_fs_1.existsSync)(path) ? (0, node_fs_1.realpathSync)(path) : path;
+    const mode = (0, node_fs_1.existsSync)(target) ? (0, node_fs_1.statSync)(target).mode & 0o777 : 0o600;
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(target), { recursive: true, mode: 0o700 });
+    const temporary = `${target}.${process.pid}.${(0, node_crypto_1.randomUUID)()}.tmp`;
+    try {
+        (0, node_fs_1.writeFileSync)(temporary, content, { mode, flag: "wx" });
+        (0, node_fs_1.renameSync)(temporary, target);
+    }
+    catch (err) {
+        (0, node_fs_1.rmSync)(temporary, { force: true });
+        throw err;
+    }
+}

package/dist/diff.d.ts

@@ -0,0 +1 @@
+export declare function lineDiff(before: string, after: string): string[];

package/dist/diff.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lineDiff = lineDiff;
+const CONTEXT_LINES = 3;
+function lines(text) {
+    const split = text.split("\n");
+    if (split[split.length - 1] === "")
+        split.pop();
+    return split;
+}
+function fullDiff(a, b) {
+    const table = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    for (let i = a.length - 1; i >= 0; i--) {
+        for (let j = b.length - 1; j >= 0; j--)
+            table[i][j] = a[i] === b[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length || j < b.length) {
+        if (i < a.length && j < b.length && a[i] === b[j]) {
+            out.push(`  ${a[i++]}`);
+            j++;
+        }
+        else if (i < a.length && (j >= b.length || table[i + 1][j] >= table[i][j + 1])) {
+            out.push(`- ${a[i++]}`);
+        }
+        else {
+            out.push(`+ ${b[j++]}`);
+        }
+    }
+    return out;
+}
+function lineDiff(before, after) {
+    const all = fullDiff(lines(before), lines(after));
+    const changed = all.map((line, index) => (line.startsWith("  ") ? -1 : index)).filter((index) => index >= 0);
+    const near = (index) => changed.some((c) => Math.abs(c - index) <= CONTEXT_LINES);
+    const out = [];
+    all.forEach((line, index) => {
+        if (near(index))
+            out.push(line);
+        else if (out[out.length - 1] !== "  ...")
+            out.push("  ...");
+    });
+    return out;
+}

package/dist/exit-codes.d.ts

@@ -0,0 +1,19 @@
+export declare const EXIT: {
+    readonly ok: 0;
+    readonly failure: 1;
+    readonly usage: 2;
+    readonly conflict: 3;
+    readonly notFound: 4;
+    readonly auth: 5;
+    readonly timeout: 6;
+    readonly ruleDeny: 10;
+    readonly ruleAsk: 11;
+    readonly unreachable: 69;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+export declare class CliError extends Error {
+    readonly exitCode: ExitCode;
+    readonly status?: number | undefined;
+    constructor(exitCode: ExitCode, message: string, status?: number | undefined);
+}
+export declare function exitCodeForStatus(status: number): ExitCode;

package/dist/exit-codes.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliError = exports.EXIT = void 0;
+exports.exitCodeForStatus = exitCodeForStatus;
+exports.EXIT = { ok: 0, failure: 1, usage: 2, conflict: 3, notFound: 4, auth: 5, timeout: 6, ruleDeny: 10, ruleAsk: 11, unreachable: 69 };
+class CliError extends Error {
+    exitCode;
+    status;
+    constructor(exitCode, message, status) {
+        super(message);
+        this.exitCode = exitCode;
+        this.status = status;
+        this.name = "CliError";
+    }
+}
+exports.CliError = CliError;
+function exitCodeForStatus(status) {
+    if (status === 401 || status === 403)
+        return exports.EXIT.auth;
+    if (status === 404)
+        return exports.EXIT.notFound;
+    if (status === 409 || status === 410)
+        return exports.EXIT.conflict;
+    if (status === 400)
+        return exports.EXIT.usage;
+    return exports.EXIT.failure;
+}

package/dist/hook-ask.d.ts

@@ -0,0 +1,39 @@
+import { AgentApi } from "./client";
+export interface AskPattern {
+    tool: string;
+    target?: string;
+}
+export interface HookAskSettings {
+    patterns: AskPattern[];
+    waitSeconds: number;
+}
+export interface ToolCall {
+    tool: string;
+    raw: string;
+    target: string;
+    matched: string;
+    summary: string;
+    exact: boolean;
+    cwd?: string;
+}
+export interface Waiting {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+export interface Verdict {
+    decision: "allow" | "deny";
+    reason: string;
+}
+export declare const DEFAULT_ASK_PATTERNS: AskPattern[];
+export declare const DEFAULT_WAIT_SECONDS = 120;
+export declare const MAX_WAIT_SECONDS = 3600;
+export declare function globMatches(pattern: string, value: string): boolean;
+export declare function wordTailMatcher(pattern: string): RegExp;
+export declare function commandSegments(command: string): string[];
+export declare function canonicalWords(words: string[]): string[];
+export declare function shellCandidates(command: string): string[];
+export declare function askMatch(patterns: AskPattern[], tool: string, raw: string): string | null;
+export declare function needsAssent(patterns: AskPattern[], tool: string, raw: string): boolean;
+export declare function hookAskSettings(file: Record<string, unknown>, env: NodeJS.ProcessEnv): HookAskSettings;
+export declare function visible(text: string): string;
+export declare function askAssent(api: AgentApi, clock: Waiting, call: ToolCall, waitSeconds: number): Promise<Verdict>;