* The endpoint path for operator fleet targets.

 */

export const FLEET_TARGETS_PATH = `${API_VERSION_PATH}/admin/forge/targets`;

/**

 * The endpoint path for the account's cloud memories.

 *

 * Named once because two callers share it: the Effect-based `MemoryClient`

 * behind `openagents memory`, and the `remember` tool a coder session declares,

 * which posts here directly rather than through the CLI runtime.

 */

export const MEMORIES_PATH = `${API_VERSION_PATH}/memories`;

/**

 * The client for the account's cloud memories.

 *

 * Memories live in the openagents.com database, account-scoped, not in a file

 * on this machine (OpenAgentsInc/openagents#51). That decision is what makes

 * this a client at all: the CLI, the web app, and a direct API caller write to

 * one store, and recall happens server-side inside `POST /api/v1/responses`,

 * so nothing here retrieves anything. These three calls — write one, read them

 * back, remove one — are the whole client surface.

 *

 * There is no update. A correction is a new memory carrying `supersedes`, so

 * the store keeps the chain a wrong memory was corrected through rather than

 * overwriting the row that was wrong.

 */

import { Effect, Layer } from "effect";

import * as Context from "effect/Context";

import { ApiTransport } from "./api-transport.js";

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

import type { CliError } from "./errors.js";

import type { AuthenticatedApi } from "./repository-client.js";

import { asRecord, asRows, asText, makeTrackerRequest } from "./tracker-request.js";

/** The two buckets the server accepts. `user` is what a reader asks for. */

export type MemoryBucket = "learned" | "user";

export interface MemoryRecord {

  readonly id: string;

  readonly bucket: string;

  readonly body: string;

  /** The thread or session the request came out of, when one was named. */

  readonly source_ref: string | null;

  /** The id of the memory that replaced this one, once one has. */

  readonly superseded_by: string | null;

  readonly created_at: string;

}

export interface MemoryListInput extends AuthenticatedApi {

  readonly bucket?: MemoryBucket;

  readonly limit?: number;

  /** Reads the corrections behind the live rows as well. */

  readonly includeSuperseded?: boolean;

}

export interface MemoryCreateInput extends AuthenticatedApi {

  readonly body: string;

  readonly bucket?: MemoryBucket;

  readonly sourceRef?: string;

  /** The id of a live memory of this account that this one replaces. */

  readonly supersedes?: string;

}

export interface MemoryDeleteInput extends AuthenticatedApi {

  readonly memoryId: string;

}

export interface MemoryClientInterface {

  readonly list: (input: MemoryListInput) => Effect.Effect<ReadonlyArray<MemoryRecord>, CliError>;

  readonly create: (input: MemoryCreateInput) => Effect.Effect<MemoryRecord, CliError>;

  readonly remove: (input: MemoryDeleteInput) => Effect.Effect<MemoryRecord, CliError>;

}

export class MemoryClient extends Context.Service<MemoryClient, MemoryClientInterface>()(

  "@openagentsinc/cli/MemoryClient",

) {}

/** Reads one row of the server's memory view. */

const parseMemory = (row: Record<string, unknown>): MemoryRecord => ({

  id: asText(row["id"]) ?? "",

  bucket: asText(row["bucket"]) ?? "user",

  body: asText(row["body"]) ?? "",

  source_ref: asText(row["source_ref"]) ?? null,

  superseded_by: asText(row["superseded_by"]) ?? null,

  created_at: asText(row["created_at"]) ?? "",

});

export const memoryClientLayer = Layer.effect(

  MemoryClient,

  Effect.gen(function* () {

    const transport = yield* ApiTransport;

    const request = makeTrackerRequest(transport);

    const list = Effect.fn("MemoryClient.list")(function* (input: MemoryListInput) {

      const query = new URLSearchParams();

      if (input.bucket !== undefined) query.set("bucket", input.bucket);

      if (input.limit !== undefined) query.set("limit", String(input.limit));

      // The flag is only ever sent as `true`. Its absence is the default, and

      // sending `false` would read as a narrowing the server does not define.

      if (input.includeSuperseded === true) query.set("include_superseded", "true");

      const suffix = query.size === 0 ? "" : `?${query.toString()}`;

      const body = yield* request("list memories", {

        origin: input.origin,

        token: input.token,

        method: "GET",

        path: `${MEMORIES_PATH}${suffix}`,

        acceptedStatuses: [200],

      });

      return asRows(body, "memories").map(parseMemory);

    });

    const create = Effect.fn("MemoryClient.create")(function* (input: MemoryCreateInput) {

      const body = yield* request("write memory", {

        origin: input.origin,

        token: input.token,

        method: "POST",

        path: MEMORIES_PATH,

        body: {

          body: input.body,

          // The server defaults an absent bucket to `user`, but a write path

          // that names its bucket keeps working if that default ever moves.

          bucket: input.bucket ?? "user",

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

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

        },

        acceptedStatuses: [201],

      });

      return parseMemory(asRecord(asRecord(body)["memory"]));

    });

    const remove = Effect.fn("MemoryClient.remove")(function* (input: MemoryDeleteInput) {

      const body = yield* request("remove memory", {

        origin: input.origin,

        token: input.token,

        method: "DELETE",

        path: `${MEMORIES_PATH}/${encodeURIComponent(input.memoryId)}`,

        acceptedStatuses: [200],

      });

      return parseMemory(asRecord(asRecord(body)["memory"]));

    });

    return MemoryClient.of({ list, create, remove });

  }),

);

/**

 * CLI command definitions for `openagents memory`.

 *

 * Three commands, because the store has three operations. There is no `edit`:

 * a correction is `add --supersedes <id>`, which leaves the memory that was

 * wrong readable behind the one that replaced it.

 *

 * Nothing here recalls anything. Recall runs server-side inside

 * `POST /api/v1/responses`, so a memory written by `add` reaches the next turn

 * with no client plumbing at all (OpenAgentsInc/openagents#51).

 */

import { Effect, Option } from "effect";

import { Argument, Command, Flag } from "effect/unstable/cli";

import { type EndpointOverrides, type Profile } from "./endpoint.js";

import { InputError } from "./errors.js";

import { type MemoryBucket, MemoryClient, type MemoryRecord } from "./memory-client.js";

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

import { resolveApiSession } from "./session.js";

interface SharedFlags {

  readonly profile: Option.Option<Profile>;

  readonly apiUrl: Option.Option<string>;

  readonly json: boolean;

  readonly noColor: boolean;

}

const endpointOverrides = (flags: {

  readonly profile: Option.Option<Profile>;

  readonly apiUrl: Option.Option<string>;

}): EndpointOverrides => ({ profile: flags.profile, apiUrl: flags.apiUrl });

const outputMode = (json: boolean): OutputMode => (json ? "json" : "human");

const bucketFlag = Flag.string("bucket").pipe(

  Flag.optional,

  Flag.withDescription("Narrow to one bucket: user or learned"),

);

const limitFlag = Flag.integer("limit").pipe(

  Flag.optional,

  Flag.withDescription("Maximum number of memories to read"),

);

const includeSupersededFlag = Flag.boolean("include-superseded").pipe(

  Flag.withDescription("Also read the corrections behind the live memories"),

);

const supersedesFlag = Flag.string("supersedes").pipe(

  Flag.optional,

  Flag.withDescription("ID of the memory this one corrects and replaces"),

);

const sourceRefFlag = Flag.string("source-ref").pipe(

  Flag.optional,

  Flag.withDescription("Thread or session this memory came out of"),

);

const memoryIdArgument = Argument.string("memory_id").pipe(Argument.withDescription("Memory ID"));

/**

 * Reads a bucket name, or `undefined` for one the server would reject.

 *

 * Checked here rather than left to the API so a typo costs a sentence instead

 * of a round trip that comes back as a validation envelope.

 */

const readBucket = (raw: string): MemoryBucket | undefined => {

  const value = raw.trim().toLowerCase();

  return value === "learned" || value === "user" ? value : undefined;

};

/** The refusal a rejected `--bucket` earns, named for the value that was given. */

const badBucket = (raw: string): InputError =>

  new InputError({ message: `--bucket must be "user" or "learned", not "${raw}".` });

const memoryListHuman = (memories: ReadonlyArray<MemoryRecord>): ReadonlyArray<string> => {

  if (memories.length === 0) return ["No memories stored for this account."];

  const lines: string[] = [];

  for (const memory of memories) {

    // One memory per block rather than one per row: a memory is a sentence a

    // person wrote, and a column would cut most of them off.

    lines.push(`${memory.id}  [${memory.bucket}]  ${memory.created_at}`);

    lines.push(`  ${memory.body}`);

    if (memory.source_ref !== null) lines.push(`  source: ${memory.source_ref}`);

    if (memory.superseded_by !== null) {

      lines.push(`  superseded by: ${memory.superseded_by}`);

    }

  }

  return lines;

};

export const makeMemoryCommand = <R>(root: Effect.Effect<SharedFlags, never, R>) => {

  const memoryListCommand = Command.make(

    "list",

    { bucket: bucketFlag, limit: limitFlag, includeSuperseded: includeSupersededFlag },

    ({ bucket, includeSuperseded, limit }) =>

      Effect.gen(function* () {

        const parsedBucket = Option.isNone(bucket) ? undefined : readBucket(bucket.value);

        if (Option.isSome(bucket) && parsedBucket === undefined) {

          return yield* badBucket(bucket.value);

        }

        const flags = yield* root;

        const session = yield* resolveApiSession(endpointOverrides(flags));

        const client = yield* MemoryClient;

        const output = yield* Output;

        const memories = yield* client.list({

          origin: session.endpoint.origin,

          token: session.token,

          ...(parsedBucket === undefined ? {} : { bucket: parsedBucket }),

          ...(Option.isNone(limit) ? {} : { limit: limit.value }),

          ...(includeSuperseded ? { includeSuperseded: true } : {}),

        });

        yield* output.write(

          {

            value: { memories },

            human: memoryListHuman(memories),

          },

          outputMode(flags.json),

        );

      }),

  ).pipe(Command.withDescription("List the account's memories, newest first"));

  const memoryAddCommand = Command.make(

    "add",

    {

      bucket: bucketFlag,

      supersedes: supersedesFlag,

      sourceRef: sourceRefFlag,

      body: Argument.string("body").pipe(

        Argument.withDescription("What to remember"),

        Argument.variadic({ min: 1 }),

      ),

    },

    ({ body, bucket, sourceRef, supersedes }) =>

      Effect.gen(function* () {

        const parsedBucket = Option.isNone(bucket) ? undefined : readBucket(bucket.value);

        if (Option.isSome(bucket) && parsedBucket === undefined) {

          return yield* badBucket(bucket.value);

        }

        const text = body.join(" ").trim();

        if (text.length === 0) {

          return yield* new InputError({ message: "A memory needs a body to store." });

        }

        const flags = yield* root;

        const session = yield* resolveApiSession(endpointOverrides(flags));

        const client = yield* MemoryClient;

        const output = yield* Output;

        const memory = yield* client.create({

          origin: session.endpoint.origin,

          token: session.token,

          body: text,

          ...(parsedBucket === undefined ? {} : { bucket: parsedBucket }),

          ...(Option.isNone(supersedes) ? {} : { supersedes: supersedes.value }),

          ...(Option.isNone(sourceRef) ? {} : { sourceRef: sourceRef.value }),

        });

        yield* output.write(

          {

            value: { memory },

            human: [

              `Stored memory ${memory.id} in the ${memory.bucket} bucket.`,

              `  ${memory.body}`,

              ...(Option.isNone(supersedes) ? [] : [`Supersedes ${supersedes.value}.`]),

            ],

          },

          outputMode(flags.json),

        );

      }),

  ).pipe(

    Command.withDescription(

      "Store one memory. Pass --supersedes <id> to correct an existing one rather than edit it",

    ),

  );

  const memoryDeleteCommand = Command.make(

    "delete",

    { memoryId: memoryIdArgument },

    ({ memoryId }) =>

      Effect.gen(function* () {

        const flags = yield* root;

        const session = yield* resolveApiSession(endpointOverrides(flags));

        const client = yield* MemoryClient;

        const output = yield* Output;

        const memory = yield* client.remove({

          origin: session.endpoint.origin,

          token: session.token,

          memoryId,

        });

        yield* output.write(

          {

            value: { memory },

            human: [`Removed memory ${memory.id}.`, `  ${memory.body}`],

          },

          outputMode(flags.json),

        );

      }),

  ).pipe(Command.withDescription("Remove one memory outright"));

  return Command.make("memory").pipe(

    Command.withDescription(

      "Read and write the account's cloud memories. Recall is server-side; these commands do not retrieve",

    ),

    Command.withSubcommands([memoryListCommand, memoryAddCommand, memoryDeleteCommand]),

  );

};

import { forumClientLayer } from "./forum-client.js";

import { gitRunnerLayer } from "./git-runner.js";

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

import { memoryClientLayer } from "./memory-client.js";

import { outputLayer } from "./output.js";

import { persistedConfigurationLayer } from "./persisted-configuration.js";

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

const deviceLayer = deviceClientLayer.pipe(Layer.provide(transportLayer));

const issueLayer = issueClientLayer.pipe(Layer.provide(transportLayer));

const projectLayer = projectClientLayer.pipe(Layer.provide(transportLayer));

const memoryLayer = memoryClientLayer.pipe(Layer.provide(transportLayer));

const boxClient = boxClientLayer.pipe(Layer.provide(transportLayer));

const computerClient = computerClientLayer.pipe(Layer.provide(transportLayer));

const credentialsLayer = credentialStoreOsLayer.pipe(Layer.provide(NodeServices.layer));

  fleetLayer,

  issueLayer,

  projectLayer,

  memoryLayer,

  deviceLayer,

  boxClient,

  computerClient,

import * as NodeServices from "@effect/platform-node/NodeServices";

import { Effect, Layer } from "effect";

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

import { apiTransportTestLayer, type ApiRequest, type ApiResponse } from "../src/api-transport.js";

import { runCliWith } from "../src/cli.js";

import { credentialStoreUnavailableLayer } from "../src/credential-store.js";

import { environmentLayerFromValues } from "../src/environment.js";

import { gitRunnerTestLayer } from "../src/git-runner.js";

import { memoryClientLayer } from "../src/memory-client.js";

import { outputTestLayer, type OutputDocument, type OutputMode } from "../src/output.js";

import { persistedConfigurationTestLayer } from "../src/persisted-configuration.js";

import { requestBodyInputTestLayer } from "../src/request-body-input.js";

import { secretInputTestLayer } from "../src/secret-input.js";

import { terminalSessionTestLayer } from "../src/terminal-session.js";

interface Written {

  readonly document: OutputDocument;

  readonly mode: OutputMode;

}

const harness = (

  handler: (input: ApiRequest) => Effect.Effect<ApiResponse, never>,

  environment: Readonly<Record<string, string>> = { token: "test-token" },

) => {

  const written: Array<Written> = [];

  const requests: Array<ApiRequest> = [];

  const transport = apiTransportTestLayer((input) => {

    requests.push(input);

    return handler(input);

  });

  const layer = Layer.mergeAll(

    NodeServices.layer,

    environmentLayerFromValues(environment),

    persistedConfigurationTestLayer({}),

    terminalSessionTestLayer(false),

    credentialStoreUnavailableLayer,

    gitRunnerTestLayer(() => Effect.void),

    secretInputTestLayer("stdin-token"),

    requestBodyInputTestLayer({}),

    memoryClientLayer.pipe(Layer.provide(transport)),

    outputTestLayer((document, mode) =>

      Effect.sync(() => {

        written.push({ document, mode });

      }),

    ),

  );

  return { written, requests, layer };

};

const memoryRow = {

  id: "mem_1",

  bucket: "user",

  body: "Uses pnpm, not npm.",

  source_ref: "thread-7",

  superseded_by: null,

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

};

describe("openagents memory CLI commands", () => {

  it("lists the account's memories", async () => {

    const { layer, written } = harness((req) => {

      if (req.path === "/api/v1/memories" && req.method === "GET") {

        return Effect.succeed({ status: 200, body: { memories: [memoryRow] } });

      }

      return Effect.succeed({ status: 404, body: {} });

    });

    await Effect.runPromise(runCliWith(["memory", "list"]).pipe(Effect.provide(layer)));

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

    const human = written[0]!.document.human;

    expect(human.some((line) => line.includes("mem_1"))).toBe(true);

    expect(human.some((line) => line.includes("Uses pnpm, not npm."))).toBe(true);

  });

  it("narrows the listing with the bucket, limit, and superseded flags", async () => {

    const { layer, requests } = harness((req) => {

      if (req.method === "GET" && req.path.startsWith("/api/v1/memories")) {

        return Effect.succeed({ status: 200, body: { memories: [] } });

      }

      return Effect.succeed({ status: 404, body: {} });

    });

    await Effect.runPromise(

      runCliWith([

        "memory",

        "list",

        "--bucket",

        "learned",

        "--limit",

        "5",

        "--include-superseded",

      ]).pipe(Effect.provide(layer)),

    );

    expect(requests[0]!.path).toContain("bucket=learned");

    expect(requests[0]!.path).toContain("limit=5");

    expect(requests[0]!.path).toContain("include_superseded=true");

  });

  it("says the store is empty rather than printing nothing", async () => {

    const { layer, written } = harness(() =>

      Effect.succeed({ status: 200, body: { memories: [] } }),

    );

    await Effect.runPromise(runCliWith(["memory", "list"]).pipe(Effect.provide(layer)));

    expect(written[0]!.document.human.some((line) => line.includes("No memories"))).toBe(true);

  });

  it("stores a memory in the user bucket", async () => {

    const { layer, requests, written } = harness((req) => {

      if (req.path === "/api/v1/memories" && req.method === "POST") {

        return Effect.succeed({ status: 201, body: { memory: memoryRow } });

      }

      return Effect.succeed({ status: 404, body: {} });

    });

    await Effect.runPromise(

      runCliWith(["memory", "add", "Uses", "pnpm,", "not", "npm."]).pipe(Effect.provide(layer)),

    );

    expect(requests[0]!.body).toMatchObject({ body: "Uses pnpm, not npm.", bucket: "user" });

    const human = written[0]!.document.human;

    expect(human.some((line) => line.includes("Stored memory mem_1"))).toBe(true);

  });

  // A correction is a new row, never an edit: the server has no `PATCH`, and

  // the chain a wrong memory was corrected through is what makes it traceable.

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

    const { layer, requests, written } = harness((req) => {

      if (req.path === "/api/v1/memories" && req.method === "POST") {

        return Effect.succeed({

          status: 201,

          body: { memory: { ...memoryRow, id: "mem_2", body: "Uses bun, not pnpm." } },

        });

      }

      return Effect.succeed({ status: 404, body: {} });

    });

    await Effect.runPromise(

      runCliWith(["memory", "add", "--supersedes", "mem_1", "Uses", "bun,", "not", "pnpm."]).pipe(

        Effect.provide(layer),

      ),

    );

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

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

    expect(written[0]!.document.human.some((line) => line.includes("Supersedes mem_1"))).toBe(true);

  });

  it("removes one memory", async () => {

    const { layer, requests, written } = harness((req) => {

      if (req.path === "/api/v1/memories/mem_1" && req.method === "DELETE") {

        return Effect.succeed({ status: 200, body: { memory: memoryRow } });

      }

      return Effect.succeed({ status: 404, body: {} });

    });

    await Effect.runPromise(runCliWith(["memory", "delete", "mem_1"]).pipe(Effect.provide(layer)));

    expect(requests[0]!.method).toBe("DELETE");

    expect(written[0]!.document.human.some((line) => line.includes("Removed memory mem_1"))).toBe(

      true,

    );

  });

  it("reports a memory the server does not hold", async () => {

    const { layer } = harness(() =>

      Effect.succeed({

        status: 404,

        body: { code: "not_found", message: "No memory with that id.", errors: {} },

      }),

    );

    const failure = await Effect.runPromise(

      runCliWith(["memory", "delete", "mem_gone"]).pipe(Effect.provide(layer), Effect.flip),

    );

    expect(JSON.stringify(failure)).toContain("not_found");

  });

  // The refusal has to survive as a refusal. A write that was rejected and

  // reported as a success would tell the reader their preference is stored.

  it("surfaces a rejected credential rather than reporting a write", async () => {

    const { layer, written } = harness(() =>

      Effect.succeed({

        status: 401,

        body: {

          code: "unauthenticated",

          error: "invalid_api_token",

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

          errors: {},

        },

      }),

    );

    const failure = await Effect.runPromise(

      runCliWith(["memory", "add", "Uses", "pnpm."]).pipe(Effect.provide(layer), Effect.flip),

    );

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

    expect(JSON.stringify(failure)).toContain("unauthenticated");

  });

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

    const { layer, written } = harness(() =>

      Effect.succeed({

        status: 429,

        body: {

          code: "memory_quota_reached",

          message:

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

          errors: {},

        },

      }),

    );

    const failure = await Effect.runPromise(

      runCliWith(["memory", "add", "One", "more", "thing."]).pipe(

        Effect.provide(layer),

        Effect.flip,

      ),

    );

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

    const reported = JSON.stringify(failure);

    expect(reported).toContain("memory_quota_reached");

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

  });

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

    const { layer } = harness(() =>

      Effect.succeed({

        status: 422,

        body: {

          code: "validation_failed",

          message: "The request could not be processed",

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

        },

      }),

    );

    const failure = await Effect.runPromise(

      runCliWith(["memory", "add", "--supersedes", "mem_absent", "Something."]).pipe(

        Effect.provide(layer),

        Effect.flip,

      ),

    );

    expect(JSON.stringify(failure)).toContain("names no live memory");

  });

  it("refuses a bucket the server would reject, without a round trip", async () => {

    const { layer, requests } = harness(() => Effect.succeed({ status: 200, body: {} }));

    const failure = await Effect.runPromise(

      runCliWith(["memory", "list", "--bucket", "system"]).pipe(Effect.provide(layer), Effect.flip),

    );

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

    expect(JSON.stringify(failure)).toContain("--bucket");

  });

  it("refuses without a credential rather than writing nowhere", async () => {

    const { layer, requests } = harness(() => Effect.succeed({ status: 201, body: {} }), {});

    const failure = await Effect.runPromise(

      runCliWith(["memory", "add", "Uses", "pnpm."]).pipe(Effect.provide(layer), Effect.flip),

    );

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

    expect(JSON.stringify(failure)).toContain("token");

  });

});