@trylucy/agent-memory 0.0.0-stage → 0.1.2

package/src/client/http-transport.mjs

@@ -0,0 +1,212 @@
+import { isIP } from 'node:net';
+import { MalformedResponseError, ValidationFailureError } from './errors.mjs';
+
+const PREFIX = '/api/lucy/agent-memory/v1';
+const DEFAULT_MAX_RETRIES = 2;
+const MAX_RESPONSE_BYTES = 65_536;
+const MAX_RETRY_AFTER_MS = 60_000;
+
+function isLoopbackHostname(hostname) {
+  if (hostname === 'localhost') return true;
+  const literal = hostname.startsWith('[') && hostname.endsWith(']')
+    ? hostname.slice(1, -1)
+    : hostname;
+  if (isIP(literal) === 4) return literal.split('.')[0] === '127';
+  return isIP(literal) === 6 && literal === '::1';
+}
+
+function normalizeBaseUrl(baseUrl, allowInsecureLoopback) {
+  if (typeof baseUrl !== 'string' || baseUrl.length === 0 || /[\r\n\0]/.test(baseUrl)) {
+    throw new ValidationFailureError('baseUrl must be a non-empty http(s) URL.');
+  }
+  let url;
+  try { url = new URL(baseUrl); } catch { throw new ValidationFailureError('baseUrl must be a valid URL.'); }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new ValidationFailureError('baseUrl must use http or https.');
+  }
+  if (url.protocol === 'http:' && !(allowInsecureLoopback && isLoopbackHostname(url.hostname))) {
+    throw new ValidationFailureError('baseUrl must use https; cleartext HTTP requires explicit loopback development opt-in.');
+  }
+  return url.origin + url.pathname.replace(/\/+$/, '');
+}
+
+function parseRetryAfterMs(value) {
+  if (value == null || value === '') return undefined;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.min(MAX_RETRY_AFTER_MS, Math.trunc(seconds * 1000));
+  const date = Date.parse(value);
+  if (Number.isFinite(date)) return Math.min(MAX_RETRY_AFTER_MS, Math.max(0, date - Date.now()));
+  return undefined;
+}
+
+function abortReason(signal) {
+  if (signal?.reason !== undefined) return signal.reason;
+  return new DOMException('The operation was aborted.', 'AbortError');
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortReason(signal);
+}
+
+async function defaultSleep(ms, signal) {
+  throwIfAborted(signal);
+  await new Promise((resolve, reject) => {
+    const finish = () => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    };
+    const timer = setTimeout(finish, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+      reject(abortReason(signal));
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+async function waitForRetry(ms, signal, sleep) {
+  throwIfAborted(signal);
+  let onAbort;
+  const aborted = new Promise((_, reject) => {
+    onAbort = () => reject(abortReason(signal));
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+  try {
+    await Promise.race([Promise.resolve().then(() => sleep(ms, signal)), aborted]);
+  } finally {
+    signal?.removeEventListener('abort', onAbort);
+  }
+}
+
+async function readResponseBody(response, signal) {
+  const reader = response?.body?.getReader?.();
+  if (!reader) {
+    throw new MalformedResponseError('Lucy response does not expose a bounded streaming body.', { status: response?.status });
+  }
+
+  const chunks = [];
+  let byteLength = 0;
+  try {
+    while (true) {
+      throwIfAborted(signal);
+      const { done, value } = await reader.read();
+      if (done) break;
+      const chunk = value instanceof Uint8Array ? value : new Uint8Array(value);
+      byteLength += chunk.byteLength;
+      if (byteLength > MAX_RESPONSE_BYTES) {
+        try { await reader.cancel(); } catch { /* retain the bounded-response error */ }
+        throw new MalformedResponseError(`Lucy response exceeds ${MAX_RESPONSE_BYTES} bytes.`, { status: response.status });
+      }
+      chunks.push(chunk);
+    }
+  } finally {
+    reader.releaseLock?.();
+  }
+  return { rawText: Buffer.concat(chunks, byteLength).toString('utf8'), byteLength };
+}
+
+function routeFor(operation, payload) {
+  if (operation === 'recall') {
+    return { method: 'POST', path: `${PREFIX}/recall`, body: payload };
+  }
+  if (operation === 'canonical-recall') {
+    return { method: 'POST', path: `${PREFIX}/recall`, body: payload, projection: 'canonical-v1' };
+  }
+  if (operation === 'propose') {
+    return { method: 'POST', path: `${PREFIX}/proposals`, body: payload };
+  }
+  if (operation === 'proposal-status') {
+    let parsed;
+    try { parsed = JSON.parse(payload); } catch { parsed = {}; }
+    const id = typeof parsed.proposal_id === 'string' ? parsed.proposal_id : '';
+    return { method: 'GET', path: `${PREFIX}/proposals/${encodeURIComponent(id)}`, body: null };
+  }
+  throw new ValidationFailureError(`Unsupported Agent Memory operation: ${operation}`);
+}
+
+function idempotencyKey(payload) {
+  try {
+    const parsed = JSON.parse(payload);
+    return typeof parsed.idempotency_key === 'string' ? parsed.idempotency_key : null;
+  } catch {
+    return null;
+  }
+}
+
+function requestId(payload) {
+  try {
+    const parsed = JSON.parse(payload);
+    return typeof parsed.request_id === 'string' ? parsed.request_id : null;
+  } catch {
+    return null;
+  }
+}
+
+function shouldRetry(operation, status, attempt, maxRetries) {
+  if (operation !== 'propose') return false;
+  return attempt < maxRetries && (status === 429 || status === 503 || status === 502 || status === 504);
+}
+
+export function createLucyHttpTransport({
+  baseUrl,
+  allowInsecureLoopback = false,
+  fetchImpl = globalThis.fetch,
+  maxRetries = DEFAULT_MAX_RETRIES,
+  sleep = defaultSleep,
+} = {}) {
+  if (typeof allowInsecureLoopback !== 'boolean') throw new ValidationFailureError('allowInsecureLoopback must be a boolean.');
+  const origin = normalizeBaseUrl(baseUrl, allowInsecureLoopback);
+  if (typeof fetchImpl !== 'function') throw new ValidationFailureError('fetchImpl must be a function.');
+  if (!Number.isInteger(maxRetries) || maxRetries < 0 || maxRetries > 5) {
+    throw new ValidationFailureError('maxRetries must be an integer from 0 through 5.');
+  }
+
+  return async function lucyHttpTransport(request) {
+    const { operation, payload, accessToken, signal } = request;
+    const route = routeFor(operation, payload);
+    const headers = {
+      accept: 'application/json',
+      authorization: `Bearer ${accessToken}`,
+    };
+    if (route.body != null) headers['content-type'] = 'application/json';
+    if (route.projection) headers['x-lucy-memory-projection'] = route.projection;
+    const key = route.method === 'POST' && operation === 'propose' ? idempotencyKey(payload) : null;
+    if (key) headers['idempotency-key'] = key;
+    const rid = requestId(payload);
+    if (rid) headers['x-request-id'] = rid;
+
+    let attempt = 0;
+    let last;
+    while (true) {
+      throwIfAborted(signal);
+      const response = await fetchImpl(origin + route.path, {
+        method: route.method,
+        headers,
+        body: route.body,
+        signal,
+        redirect: 'error',
+      });
+      const { rawText, byteLength } = await readResponseBody(response, signal);
+      let body = null;
+      if (rawText.length > 0) {
+        try { body = JSON.parse(rawText); } catch { body = rawText; }
+      }
+      const retryAfterMs = parseRetryAfterMs(response.headers.get('retry-after'));
+      const memoryOperationId = response.headers.get('x-lucy-memory-operation-id');
+      last = {
+        status: response.status,
+        body,
+        byteLength,
+        ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+        ...(typeof memoryOperationId === 'string' && memoryOperationId.length > 0
+          ? { memoryOperationId }
+          : {}),
+      };
+      if (!shouldRetry(operation, response.status, attempt, maxRetries)) return last;
+      attempt += 1;
+      const wait = retryAfterMs ?? 0;
+      if (wait > 0) await waitForRetry(wait, signal, sleep);
+    }
+  };
+}

package/src/client/index.d.ts

@@ -0,0 +1,243 @@
+export type MemoryKind = 'fact' | 'preference' | 'decision' | 'rule';
+export type MemoryLifecycle = 'active' | 'superseded' | 'revoked' | 'forgotten';
+export type ProposalLifecycle = 'pending' | 'approved' | 'rejected' | 'expired' | 'superseded';
+export type PublicPermission = 'memory:read' | 'memory:propose';
+
+export type UserScope = Readonly<{ kind: 'user' }>;
+export type WorkspaceScope = Readonly<{ kind: 'workspace' }>;
+export type ProjectScope = Readonly<{ kind: 'project'; id: `project_${string}` }>;
+export type MemoryScope = UserScope | WorkspaceScope | ProjectScope;
+
+export interface ReceiptRelation {
+  type: 'supersedes';
+  memory_id: `mem_${string}`;
+  memory_version: number;
+}
+
+export interface MemoryReceipt {
+  schema_version: '1';
+  id: `rcpt_${string}`;
+  memory_id: `mem_${string}`;
+  memory_version: number;
+  key: string;
+  kind: MemoryKind;
+  scope: MemoryScope;
+  lifecycle: MemoryLifecycle;
+  authority: { type: 'human_approved' };
+  authoritative_at: string;
+  issued_at: string;
+  provenance: { type: 'governed_record'; ref: string };
+  relations: ReceiptRelation[];
+}
+
+export interface ActiveMemory {
+  schema_version: '1';
+  id: `mem_${string}`;
+  version: number;
+  key: string;
+  kind: MemoryKind;
+  scope: MemoryScope;
+  content: string;
+  status: 'active';
+  receipt: MemoryReceipt;
+}
+
+export interface RecallRequest {
+  query: string;
+  scope: MemoryScope;
+  keys?: string[];
+  kinds?: MemoryKind[];
+  limit?: number;
+}
+
+export interface RecallResponse {
+  schema_version: '1';
+  request_id: `req_${string}`;
+  as_of: string;
+  consistency: 'canonical_active';
+  scope: MemoryScope;
+  results: ActiveMemory[];
+  notices: string[];
+  /** Present when Lucy returns x-lucy-memory-operation-id; attached after AM-01 validation. */
+  operation_id?: string;
+}
+
+export type CanonicalApprovalStatus = 'user_approved' | 'approved' | 'replayed' | 'controller_approved';
+export interface CanonicalProvenance {
+  type: 'lucy_canonical';
+  record_id: string;
+  proposal_id: string | null;
+  canonical_payload_hash: string | null;
+  written_at: string;
+}
+export interface CanonicalRecallResult {
+  record_id: string;
+  key: string | null;
+  kind: string;
+  scope: MemoryScope;
+  content: string;
+  status: 'active';
+  persisted: true;
+  /** Native approval state; controller_approved does not claim a human receipt. */
+  approval_status: CanonicalApprovalStatus;
+  version: number | null;
+  provenance: CanonicalProvenance;
+}
+export interface CanonicalRecallResponse {
+  schema_version: 'canonical-recall-1';
+  request_id: `req_${string}`;
+  as_of: string;
+  consistency: 'canonical_active';
+  scope: MemoryScope;
+  results: CanonicalRecallResult[];
+  notices: [];
+  operation_id?: string;
+}
+
+export interface CreateProposalRequest {
+  operation: 'create';
+  key: string;
+  kind: MemoryKind;
+  scope: MemoryScope;
+  content: string;
+  justification: string;
+  idempotency_key: string;
+  source_ref?: string;
+}
+
+export interface ReplaceProposalRequest {
+  operation: 'replace';
+  memory_id: `mem_${string}`;
+  expected_version: number;
+  key: string;
+  scope: MemoryScope;
+  content: string;
+  justification: string;
+  idempotency_key: string;
+  source_ref?: string;
+}
+
+export type ProposalRequest = CreateProposalRequest | ReplaceProposalRequest;
+
+export interface ProposalResult {
+  memory_id: `mem_${string}`;
+  memory_version: number;
+  receipt_id: `rcpt_${string}`;
+}
+
+export interface ProposalStatus {
+  schema_version: '1';
+  id: `proposal_${string}`;
+  proposal_version: 1;
+  operation: 'create' | 'replace';
+  status: ProposalLifecycle;
+  requested: {
+    memory_id?: `mem_${string}`;
+    expected_version?: number;
+    key: string;
+    kind: MemoryKind;
+    scope: MemoryScope;
+  };
+  relations: [];
+  created_at: string;
+  expires_at: string;
+  decided_at: string | null;
+  result: ProposalResult | null;
+  /** Present when Lucy returns x-lucy-memory-operation-id; attached after AM-01 validation. */
+  operation_id?: string;
+}
+
+export interface ProposalStatusRequest {
+  proposal_id: `proposal_${string}`;
+}
+
+export interface TransportRequest {
+  operation: 'recall' | 'canonical-recall' | 'propose' | 'proposal-status';
+  payload: string;
+  accessToken: string;
+  signal: AbortSignal;
+}
+
+export interface TransportResponse {
+  status: number;
+  body: unknown;
+  byteLength: number;
+  retryAfterMs?: number;
+  /** Echo of Lucy response header x-lucy-memory-operation-id when present. */
+  memoryOperationId?: string;
+}
+
+export type AgentMemoryTransport = (request: Readonly<TransportRequest>) => Promise<TransportResponse>;
+
+export interface AgentMemoryClientOptions {
+  transport: AgentMemoryTransport;
+  token: string;
+  permissions: PublicPermission[];
+  timeoutMs?: number;
+}
+
+export type RecallRequestJson = string;
+export type ProposalRequestJson = string;
+export type ProposalStatusRequestJson = string;
+
+export { createLucyHttpTransport, type LucyHttpTransportOptions } from './http-transport.js';
+
+export class AgentMemoryClient {
+  constructor(options: AgentMemoryClientOptions);
+  recall(requestJson: RecallRequestJson): Promise<RecallResponse>;
+  recallCanonical(requestJson: RecallRequestJson): Promise<CanonicalRecallResponse>;
+  propose(requestJson: ProposalRequestJson): Promise<ProposalStatus>;
+  proposalStatus(requestJson: ProposalStatusRequestJson): Promise<ProposalStatus>;
+}
+
+export interface AgentMemoryErrorOptions {
+  code?: string;
+  status?: number | null;
+  retryable?: boolean;
+  details?: unknown;
+}
+
+export class AgentMemoryError extends Error {
+  readonly code: string;
+  readonly status: number | null;
+  readonly retryable: boolean;
+  readonly details: unknown;
+  constructor(message: string, options?: AgentMemoryErrorOptions);
+}
+
+export class AuthenticationFailureError extends AgentMemoryError { constructor(message?: string, options?: AgentMemoryErrorOptions); }
+export class AuthorizationFailureError extends AgentMemoryError { constructor(message?: string, options?: AgentMemoryErrorOptions); }
+export class InvalidScopeError extends AgentMemoryError { constructor(message?: string, options?: AgentMemoryErrorOptions); }
+export class InvalidKeyError extends AgentMemoryError { constructor(message?: string, options?: AgentMemoryErrorOptions); }
+export class InvalidKindError extends AgentMemoryError { constructor(message?: string, options?: AgentMemoryErrorOptions); }
+export class ValidationFailureError extends AgentMemoryError { constructor(message?: string, options?: AgentMemoryErrorOptions); }
+export class ProposalNotFoundError extends AgentMemoryError { constructor(message?: string, options?: AgentMemoryErrorOptions); }
+export class MemoryNotFoundError extends AgentMemoryError { constructor(message?: string, options?: AgentMemoryErrorOptions); }
+export class VersionConflictError extends AgentMemoryError { constructor(message?: string, options?: AgentMemoryErrorOptions); }
+export class LifecycleConflictError extends AgentMemoryError { constructor(message?: string, options?: AgentMemoryErrorOptions); }
+export class UpstreamUnavailableError extends AgentMemoryError { constructor(message?: string, options?: AgentMemoryErrorOptions); }
+export class TimeoutError extends AgentMemoryError { constructor(message?: string, options?: AgentMemoryErrorOptions); }
+export class MalformedResponseError extends AgentMemoryError { constructor(message?: string, options?: AgentMemoryErrorOptions); }
+export class InternalLucyError extends AgentMemoryError { constructor(message?: string, options?: AgentMemoryErrorOptions); }
+export class InsufficientCreditsError extends AgentMemoryError { constructor(message?: string, options?: AgentMemoryErrorOptions); }
+export class BillingUnavailableError extends AgentMemoryError { constructor(message?: string, options?: AgentMemoryErrorOptions); }
+export class RateLimitError extends AgentMemoryError {
+  readonly retryAfterMs: number | null;
+  constructor(message?: string, options?: AgentMemoryErrorOptions & { retryAfterMs?: number | null });
+}
+
+export const MEMORY_KINDS: readonly MemoryKind[];
+export const MEMORY_LIFECYCLES: readonly MemoryLifecycle[];
+export const PROPOSAL_LIFECYCLES: readonly ProposalLifecycle[];
+export const SCOPE_KINDS: readonly MemoryScope['kind'][];
+
+export function stableSerialize(value: unknown): string;
+export function validateScope(scope: unknown): MemoryScope;
+export function validateKey(key: unknown): string;
+export function validateKind(kind: unknown): MemoryKind;
+export function validateRecallRequest(request: unknown): RecallRequest;
+export function validateProposalRequest(request: unknown): ProposalRequest;
+export function validateProposalStatusRequest(request: unknown): ProposalStatusRequest;
+export function validateRecallResponse(value: unknown, request?: RecallRequest): RecallResponse;
+export function validateCanonicalRecallResponse(value: unknown, request?: RecallRequest): CanonicalRecallResponse;
+export function validateProposalResponse(value: unknown, request?: ProposalRequest | ProposalStatusRequest): ProposalStatus;

package/src/client/index.mjs

@@ -0,0 +1,38 @@
+export { AgentMemoryClient } from './client.mjs';
+export { createLucyHttpTransport } from './http-transport.mjs';
+export {
+  AgentMemoryError,
+  AuthenticationFailureError,
+  AuthorizationFailureError,
+  InternalLucyError,
+  InvalidKeyError,
+  InvalidKindError,
+  InvalidScopeError,
+  LifecycleConflictError,
+  MalformedResponseError,
+  MemoryNotFoundError,
+  ProposalNotFoundError,
+  RateLimitError,
+  TimeoutError,
+  UpstreamUnavailableError,
+  ValidationFailureError,
+  VersionConflictError,
+  InsufficientCreditsError,
+  BillingUnavailableError,
+} from './errors.mjs';
+export { stableSerialize } from './serialization.mjs';
+export {
+  MEMORY_KINDS,
+  MEMORY_LIFECYCLES,
+  PROPOSAL_LIFECYCLES,
+  SCOPE_KINDS,
+  validateKey,
+  validateKind,
+  validateProposalRequest,
+  validateProposalResponse,
+  validateProposalStatusRequest,
+  validateRecallRequest,
+  validateRecallResponse,
+  validateScope,
+} from './validation.mjs';
+export { validateCanonicalRecallResponse } from './canonical-validation.mjs';

package/src/client/serialization.mjs

@@ -0,0 +1,53 @@
+import { ValidationFailureError } from './errors.mjs';
+
+function inertRecord(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return value;
+  const record = Object.create(null);
+  for (const key of Object.keys(value)) record[key] = value[key];
+  return record;
+}
+
+export function parseRequestJson(value, label, maxBytes) {
+  if (typeof value !== 'string') {
+    throw new ValidationFailureError(`${label} must be supplied as primitive JSON text; caller objects are not accepted.`);
+  }
+  if (Buffer.byteLength(value) > maxBytes) throw new ValidationFailureError(`${label} exceeds ${maxBytes} UTF-8 bytes.`);
+  try {
+    return JSON.parse(value, (_key, child) => inertRecord(child));
+  } catch {
+    throw new ValidationFailureError(`${label} must be valid JSON text.`);
+  }
+}
+
+function serialize(value, seen, inArray = false) {
+  if (value === null) return 'null';
+  if (value === undefined) return inArray ? 'null' : undefined;
+  if (typeof value === 'string' || typeof value === 'boolean') return JSON.stringify(value);
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new ValidationFailureError('Requests cannot contain non-finite numbers.');
+    return JSON.stringify(value);
+  }
+  if (typeof value !== 'object') throw new ValidationFailureError(`Requests cannot contain ${typeof value} values.`);
+  if (seen.has(value)) throw new ValidationFailureError('Requests cannot contain circular values.');
+  seen.add(value);
+  let result;
+  if (Array.isArray(value)) {
+    result = `[${value.map((item) => serialize(item, seen, true)).join(',')}]`;
+  } else {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) throw new ValidationFailureError('Requests may contain only plain objects and arrays.');
+    const entries = Object.keys(value).sort().flatMap((key) => {
+      const encoded = serialize(value[key], seen, false);
+      return encoded === undefined ? [] : [`${JSON.stringify(key)}:${encoded}`];
+    });
+    result = `{${entries.join(',')}}`;
+  }
+  seen.delete(value);
+  return result;
+}
+
+export function stableSerialize(value) {
+  const serialized = serialize(value, new Set());
+  if (serialized === undefined) throw new ValidationFailureError('The request body cannot be undefined.');
+  return serialized;
+}