import { startDevServer } from "./coder-dev-server.js";

import { ResponsesReplySource } from "./coder-responses.js";

import { TIER_MODELS, tierForModel, tierUnavailable, type CoderTierId } from "./coder-tiers.js";

import { rememberTool } from "./coder-remember.js";

import { ZenReplySource, zenCredential } from "./coder-zen.js";

import { describeWorkspace } from "./coder-workspace.js";

import { makeBoxCommand } from "./box-command.js";

import { makeIdentityCommand } from "./identity-command.js";

import { IssueClient } from "./issue-client.js";

import { runGitCredentialHelper } from "./git-credential-helper.js";

import { makeMemoryCommand } from "./memory-command.js";

import { Output, type OutputMode } from "./output.js";

import { ProjectClient } from "./project-client.js";

import { makeProviderCommand } from "./provider-command.js";

          // being asked for. Re-declaration per turn is what makes the tool

          // appear the turn after `/goal` sets one.

          ...(goalStore.getGoal() === undefined ? [] : [goalTool(goalStore)]),

          // The write half of the cloud memory rail

          // (OpenAgentsInc/openagents#51). Declared on every session,

          // including one with no credential: the tool refuses in a sentence

          // the model can repeat, which is what the reader needs to hear, and

          // a session that simply lacked the tool would answer that it cannot

          // remember anything. Recall needs nothing here — the server attaches

          // the account's memories inside `POST /api/v1/responses`.

          rememberTool({

            origin: endpoint.origin,

            ...(Option.isNone(stored) ? {} : { token: Redacted.value(stored.value.token) }),

            ...(transcriptThreadId === undefined ? {} : { sourceRef: transcriptThreadId }),

          }),

          ...(setup === undefined ? [] : [delegateTool(setup.delegation)]),

          capability,

          ...visiblePlugins().map((plugin) => {

const boxCommand = makeBoxCommand(rootCommand);

const memoryCommand = makeMemoryCommand(rootCommand);

// The deploy command group: named operator deployment commands over the

// operator-only fleet promotion API from OpenAgentsInc/openagents.com#57.

// It consumes only that API — never `/admin/forge`, SSH, or an internal RPC —

    forumCommand,

    identityCommand,

    issueCommand,

    memoryCommand,

    projectCommand,

    providerCommand,

    repoCommand,

/**

 * The `remember` tool: store one memory for the account.

 *

 * The write half of OpenAgentsInc/openagents#51. A memory goes to

 * `POST /api/v1/memories` in the openagents.com database, account-scoped —

 * not to a file on this machine. The local engram ledger under

 * `~/.openagents/memory` is frozen and nothing here reads or writes it.

 *

 * There is deliberately no recall tool, and no `get`. Recall runs server-side

 * inside `POST /api/v1/responses`: the server retrieves the account's relevant

 * memories against the incoming input and attaches them to the model context

 * before the provider call. The model does not go looking, and the CLI does no

 * retrieval at all. So the one genuine model action left is the one this tool

 * carries — writing down something the reader asked to have remembered.

 *

 * Explicit only, never inferred. This fires when the reader asks for something

 * to be remembered, not when a conversation happens to reveal a preference.

 * The description below says so to the model, because the description is the

 * only thing that governs when a tool is called.

 *

 * A refusal is returned as text rather than thrown. A model that is told the

 * memory could not be stored can say so; a model handed a silent success for a

 * write that never landed will tell the reader their preference is saved when

 * it is not. So every path out of this tool — no credential, a rejected token,

 * a full account, an unreachable server — names what happened.

 */

import type { CoderTool } from "./coder-tools.js";

import { MEMORIES_PATH } from "./constants.js";

import { trackerErrorDetails } from "./tracker-request.js";

/** The subset of `fetch` this tool uses. An injection seam for tests. */

export type RememberTransport = (

  input: URL,

  init: {

    readonly method: string;

    readonly headers: Readonly<Record<string, string>>;

    readonly body: string;

  },

) => Promise<{ readonly status: number; json: () => Promise<unknown> }>;

export interface RememberOptions {

  readonly origin: string;

  /**

   * The account token.

   *

   * `undefined` where the session holds no credential — an offline session, or

   * one started before `openagents auth login`. The tool is still declared in

   * that case and refuses honestly when called, rather than disappearing and

   * leaving the model to answer that it cannot remember things at all.

   */

  readonly token?: string | undefined;

  /**

   * The thread this session records to, carried onto every memory it writes.

   *

   * `undefined` on a lane that keeps no server record, which is honest: a

   * source reference naming no readable thread would be worse than none.

   */

  readonly sourceRef?: string | undefined;

  /** Injection seam for tests. Defaults to the global `fetch`. */

  readonly fetch?: RememberTransport | undefined;

}

/** Reads a JSON object, or an empty one when the value is not an object. */

const record = (value: unknown): Record<string, unknown> =>

  value !== null && typeof value === "object" && !Array.isArray(value)

    ? (value as Record<string, unknown>)

    : {};

export function rememberTool(options: RememberOptions): CoderTool {

  const send: RememberTransport =

    options.fetch ?? (globalThis.fetch.bind(globalThis) as unknown as RememberTransport);

  return {

    name: "remember",

    description:

      "Store one thing the reader has explicitly asked you to remember, in their account's " +

      "memory. Call it when they say to remember, note, or keep something — a preference, a " +

      "constraint, a fact about how they work.\n\n" +

      "Explicit requests only. Do not call this because a conversation revealed a preference, " +

      "because something seemed worth keeping, or to summarize a session. A memory exists " +

      "because somebody asked for it.\n\n" +

      "There is no matching read: the account's relevant memories are attached to your context " +

      "by the server before you see the turn, so what is remembered already reaches you without " +

      "a tool call. To correct a memory you were shown, call this with the corrected sentence " +

      "and pass the old memory's id as `supersedes`; memories are never edited in place.",

    parameters: {

      type: "object",

      properties: {

        body: {

          type: "string",

          description:

            "What to remember, as one self-contained sentence that will still make sense in a " +

            'later session with none of this conversation around it. For example: "Uses pnpm, ' +

            'not npm, in every repository."',

        },

        supersedes: {

          type: "string",

          description:

            "Optional. The id of an existing memory this one corrects and replaces. Use it " +

            "instead of writing a second, contradictory memory.",

        },

      },

      required: ["body"],

      additionalProperties: false,

    },

    run: async (args) => {

      const body = typeof args["body"] === "string" ? args["body"].trim() : "";

      if (body.length === 0) {

        return "Nothing was stored: `body` is required and must say what to remember.";

      }

      const supersedes = typeof args["supersedes"] === "string" ? args["supersedes"] : undefined;

      if (options.token === undefined) {

        return (

          "Refusal: nothing was stored. This session holds no OpenAgents credential, so it " +

          "cannot reach the account's memory. Run `openagents auth login` and ask again."

        );

      }

      const sourceRef = options.sourceRef;

      let response: { readonly status: number; json: () => Promise<unknown> };

      try {

        response = await send(new URL(MEMORIES_PATH, options.origin), {

          method: "POST",

          headers: {

            authorization: `Bearer ${options.token}`,

            "content-type": "application/json",

            accept: "application/json",

          },

          body: JSON.stringify({

            body,

            bucket: "user",

            ...(sourceRef === undefined ? {} : { source_ref: sourceRef }),

            ...(supersedes === undefined ? {} : { supersedes }),

          }),

        });

      } catch (cause) {

        return (

          `Refusal: nothing was stored. The API at ${options.origin} could not be reached ` +

          `(${String(cause)}).`

        );

      }

      const envelope = await response.json().catch(() => ({}));

      if (response.status === 201) {

        const memory = record(record(envelope)["memory"]);

        const id = typeof memory["id"] === "string" ? memory["id"] : "";

        return supersedes === undefined

          ? `Stored. Memory ${id} now holds: ${body}`

          : `Stored. Memory ${id} now holds: ${body} (it supersedes ${supersedes}.)`;

      }

      // The server's own code and sentence carry through. A full account is

      // told which limit it met and what to do about it, and a rejected field

      // is named, so the model can act rather than retry the same write.

      const details = trackerErrorDetails(envelope, response.status);

      if (response.status === 401 || response.status === 403) {

        return (

          "Refusal: nothing was stored. This session's credential cannot write the account's " +

          "memory. Run `openagents auth login` to sign in again."

        );

      }

      return `Refusal: nothing was stored. ${details.message}`;

    },

  };

}

import { describe, expect, it } from "vitest";

import { rememberTool, type RememberTransport } from "../src/coder-remember.js";

interface Sent {

  readonly url: string;

  readonly method: string;

  readonly headers: Readonly<Record<string, string>>;

  readonly body: unknown;

}

/**

 * A faked transport, recording what the tool sent and answering what the

 * server would. Nothing here touches the network or the disk, which is the

 * point: the tool must reach the API and must never write locally.

 */

const transport = (reply: (sent: Sent) => { readonly status: number; readonly body: unknown }) => {

  const sent: Array<Sent> = [];

  const send: RememberTransport = (url, init) => {

    const call: Sent = {

      url: url.toString(),

      method: init.method,

      headers: init.headers,

      body: JSON.parse(init.body) as unknown,

    };

    sent.push(call);

    const answer = reply(call);

    return Promise.resolve({

      status: answer.status,

      json: () => Promise.resolve(answer.body),

    });

  };

  return { sent, send };

};

const signal = new AbortController().signal;

/** A transport that cannot reach the server at all. */

const unreachable: RememberTransport = () => Promise.reject(new Error("ECONNREFUSED"));

describe("the remember tool", () => {

  it("posts to the memories API rather than writing a local ledger", async () => {

    const { send, sent } = transport(() => ({

      status: 201,

      body: {

        memory: {

          id: "mem_42",

          bucket: "user",

          body: "Uses pnpm, not npm.",

          source_ref: "thread-7",

          superseded_by: null,

          created_at: "2026-08-25T12:00:00Z",

        },

      },

    }));

    const tool = rememberTool({

      origin: "https://openagents.com",

      token: "account-token",

      sourceRef: "thread-7",

      fetch: send,

    });

    const answer = await tool.run({ body: "Uses pnpm, not npm." }, signal);

    expect(sent.length).toBe(1);

    expect(sent[0]!.url).toBe("https://openagents.com/api/v1/memories");

    expect(sent[0]!.method).toBe("POST");

    expect(sent[0]!.headers["authorization"]).toBe("Bearer account-token");

    // The bucket is `user` because the reader asked. Nothing this tool writes

    // is inferred, so nothing it writes is `learned`.

    expect(sent[0]!.body).toMatchObject({

      body: "Uses pnpm, not npm.",

      bucket: "user",

      source_ref: "thread-7",

    });

    expect(answer).toContain("Stored");

    expect(answer).toContain("mem_42");

  });

  it("sends a correction as a new memory carrying supersedes", async () => {

    const { send, sent } = transport(() => ({

      status: 201,

      body: { memory: { id: "mem_43", bucket: "user", body: "Uses bun." } },

    }));

    const tool = rememberTool({

      origin: "https://openagents.com",

      token: "account-token",

      fetch: send,

    });

    const answer = await tool.run({ body: "Uses bun.", supersedes: "mem_42" }, signal);

    expect(sent[0]!.body).toMatchObject({ supersedes: "mem_42" });

    expect(answer).toContain("supersedes mem_42");

  });

  it("omits the source reference on a lane that keeps no server record", async () => {

    const { send, sent } = transport(() => ({

      status: 201,

      body: { memory: { id: "mem_44" } },

    }));

    const tool = rememberTool({

      origin: "https://openagents.com",

      token: "account-token",

      fetch: send,

    });

    await tool.run({ body: "Prefers tabs." }, signal);

    expect(Object.keys(sent[0]!.body as Record<string, unknown>)).not.toContain("source_ref");

  });

  // Every failing path has to come back as a refusal the model can repeat. A

  // silent success would tell the reader their preference is stored when it is

  // not, which is the one outcome worse than not storing it.

  it("refuses honestly when the session holds no credential", async () => {

    const { send, sent } = transport(() => ({ status: 201, body: {} }));

    const tool = rememberTool({ origin: "https://openagents.com", fetch: send });

    const answer = await tool.run({ body: "Uses pnpm." }, signal);

    expect(sent.length).toBe(0);

    expect(answer).toContain("Refusal");

    expect(answer).toContain("openagents auth login");

  });

  it("refuses honestly when the server rejects the credential", async () => {

    const { send } = transport(() => ({

      status: 401,

      body: {

        code: "unauthenticated",

        message: "Requires an API token with the scope this route needs",

        errors: {},

      },

    }));

    const tool = rememberTool({

      origin: "https://openagents.com",

      token: "stale-token",

      fetch: send,

    });

    const answer = await tool.run({ body: "Uses pnpm." }, signal);

    expect(answer).toContain("Refusal");

    expect(answer).toContain("nothing was stored");

    expect(answer).toContain("openagents auth login");

  });

  it("surfaces the quota refusal with the reason the server gave", async () => {

    const { send } = transport(() => ({

      status: 429,

      body: {

        code: "memory_quota_reached",

        message:

          "This account already holds 200 memories. Remove one, or supersede one, before writing another.",

        errors: {},

      },

    }));

    const tool = rememberTool({

      origin: "https://openagents.com",

      token: "account-token",

      fetch: send,

    });

    const answer = await tool.run({ body: "One more thing." }, signal);

    expect(answer).toContain("Refusal");

    expect(answer).toContain("already holds 200 memories");

    expect(answer).toContain("supersede one");

  });

  it("names the rejected field on a validation refusal", async () => {

    const { send } = transport(() => ({

      status: 422,

      body: {

        code: "validation_failed",

        message: "The request could not be processed",

        errors: { supersedes: ["names no live memory of this account"] },

      },

    }));

    const tool = rememberTool({

      origin: "https://openagents.com",

      token: "account-token",

      fetch: send,

    });

    const answer = await tool.run({ body: "Something.", supersedes: "mem_absent" }, signal);

    expect(answer).toContain("Refusal");

    expect(answer).toContain("supersedes: names no live memory of this account");

  });

  it("refuses honestly when the API cannot be reached", async () => {

    const tool = rememberTool({

      origin: "https://openagents.com",

      token: "account-token",

      fetch: unreachable,

    });

    const answer = await tool.run({ body: "Uses pnpm." }, signal);

    expect(answer).toContain("Refusal");

    expect(answer).toContain("could not be reached");

  });

  it("refuses an empty body without spending a request", async () => {

    const { send, sent } = transport(() => ({ status: 201, body: {} }));

    const tool = rememberTool({

      origin: "https://openagents.com",

      token: "account-token",

      fetch: send,

    });

    const answer = await tool.run({ body: "   " }, signal);

    expect(sent.length).toBe(0);

    expect(answer).toContain("`body` is required");

  });

  // Recall is server-side inside `POST /api/v1/responses`, so the declaration

  // carries a write and nothing else. A read tool here would be the model

  // spending a round on context the server already attached.

  it("declares one write action and no read", async () => {

    const tool = rememberTool({ origin: "https://openagents.com", token: "t" });

    expect(tool.name).toBe("remember");

    expect(tool.description).toContain("Explicit requests only");

    expect(tool.description).toContain("There is no matching read");

    const properties = (tool.parameters as { properties: Record<string, unknown> }).properties;

    expect(Object.keys(properties)).toEqual(["body", "supersedes"]);

  });

});