synomem 0.3.0 → 0.5.0

package/src/discover.ts

@@ -0,0 +1,155 @@
+/*
+ * Finding out which workspace a credential belongs to, so nobody has to type
+ * one from memory.
+ *
+ * A hosted workspace ID looks like `ws-04psqx2rkt8ttft7a1t2z69r97`. Asking a
+ * person to enter that during setup is asking them to leave and go find it, and
+ * the credential they just authorized already knows the answer -- or knows
+ * enough to offer a short list.
+ *
+ * Two credentials, two routes, because they carry different authority:
+ *
+ *   An installation access key is bound to exactly one workspace. There is
+ *   nothing to choose, so `discoverBoundWorkspace` reads it off the data plane
+ *   and setup asks nothing at all.
+ *
+ *   A browser sign-in authorizes an ACCOUNT, which may reach several
+ *   organizations, each with several workspaces. `discoverOrganizations` lists
+ *   them for selection.
+ */
+import { SynomemError } from './errors.js';
+
+export interface DiscoveredWorkspace {
+  id: string;
+  displayName: string;
+}
+
+export interface DiscoveredOrganization {
+  id: string;
+  slug: string;
+  displayName: string;
+  role: string;
+  workspaces: DiscoveredWorkspace[];
+}
+
+export interface DiscoveryOptions {
+  baseUrl: string;
+  accessToken: string;
+  /** Injected by tests. Defaults to the global fetch. */
+  fetch?: typeof globalThis.fetch;
+  signal?: AbortSignal;
+}
+
+interface Envelope<T> {
+  ok?: boolean;
+  data?: T;
+  error?: { code?: string; message?: string };
+}
+
+async function readJson<T>(options: DiscoveryOptions, path: string): Promise<T> {
+  const request = options.fetch ?? globalThis.fetch;
+  const url = new URL(
+    path,
+    options.baseUrl.endsWith('/') ? options.baseUrl : `${options.baseUrl}/`,
+  );
+  let response: Response;
+  try {
+    response = await request(url, {
+      headers: { authorization: `Bearer ${options.accessToken}`, accept: 'application/json' },
+      ...(options.signal ? { signal: options.signal } : {}),
+    });
+  } catch (error) {
+    throw new SynomemError(
+      'REMOTE_UNAVAILABLE',
+      `Could not reach ${url.origin}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  let body: Envelope<T>;
+  try {
+    body = (await response.json()) as Envelope<T>;
+  } catch {
+    throw new SynomemError('REMOTE_PROTOCOL', `${url.pathname} did not return JSON.`);
+  }
+  if (!response.ok || body.ok !== true || body.data === undefined) {
+    // 401 and 403 are the ones a person can act on, so they keep their own
+    // codes rather than being flattened into a generic protocol error.
+    const code =
+      response.status === 401 ? 'AUTH_REQUIRED' : response.status === 403 ? 'AUTH_FORBIDDEN' : null;
+    const message = body.error?.message ?? `${url.pathname} returned ${response.status}.`;
+    throw new SynomemError(code ?? 'REMOTE_PROTOCOL', message);
+  }
+  return body.data;
+}
+
+/**
+ * The single workspace an installation access key can address.
+ *
+ * Answered by the data plane rather than the control plane: an installation key
+ * is not an account principal, so it cannot list organizations, but it can
+ * always say where it is bound.
+ */
+export async function discoverBoundWorkspace(
+  options: DiscoveryOptions,
+): Promise<{ workspaceId: string; actor: { kind: string; id: string; displayName?: string } }> {
+  const identity = await readJson<{
+    workspaceId: string;
+    actor: { kind: string; id: string; displayName?: string };
+  }>(options, 'v1/identity');
+  if (!identity.workspaceId) {
+    throw new SynomemError('REMOTE_PROTOCOL', 'The service did not report a bound workspace.');
+  }
+  return { workspaceId: identity.workspaceId, actor: identity.actor };
+}
+
+/**
+ * Every organization this account belongs to, each with its workspaces.
+ *
+ * Organizations are listed even when they hold no workspaces yet, because
+ * "you belong to this organization and it is empty" is a different and more
+ * useful answer than omitting it and appearing to have found nothing.
+ */
+export async function discoverOrganizations(
+  options: DiscoveryOptions,
+): Promise<DiscoveredOrganization[]> {
+  const me = await readJson<{
+    organizations: { id: string; slug: string; displayName: string; role: string }[];
+  }>(options, 'v1/me');
+  const organizations: DiscoveredOrganization[] = [];
+  for (const organization of me.organizations ?? []) {
+    const workspaces = await readJson<{ id: string; displayName: string }[]>(
+      options,
+      `v1/organizations/${encodeURIComponent(organization.id)}/workspaces`,
+    );
+    organizations.push({
+      id: organization.id,
+      slug: organization.slug,
+      displayName: organization.displayName,
+      role: organization.role,
+      workspaces: (workspaces ?? []).map((workspace) => ({
+        id: workspace.id,
+        displayName: workspace.displayName,
+      })),
+    });
+  }
+  return organizations;
+}
+
+/** Flattens discovery into the choices a person picks from. */
+export function workspaceChoices(
+  organizations: DiscoveredOrganization[],
+): Array<{ value: string; label: string; detail?: string }> {
+  const choices: Array<{ value: string; label: string; detail?: string }> = [];
+  for (const organization of organizations) {
+    for (const workspace of organization.workspaces) {
+      choices.push({
+        value: workspace.id,
+        // The organization is part of the label, not the detail: two
+        // organizations may both have a workspace called "Production", and the
+        // label is the only part a person is guaranteed to read.
+        label: `${organization.displayName} / ${workspace.displayName}`,
+        detail: workspace.id,
+      });
+    }
+  }
+  return choices;
+}

package/src/index.ts

@@ -11,7 +11,12 @@ export {
 export { RemoteSynomemService, environmentCredentialProvider } from './remote.js';
 export type { SynomemCredentialProvider, RemoteSynomemOptions } from './remote.js';
 export { credentialReference, OsCredentialStore } from './credentials.js';
-export type { CredentialStore, StoredOAuthCredential } from './credentials.js';
+export type {
+  CredentialStore,
+  StoredCredential,
+  StoredInstallationKey,
+  StoredOAuthCredential,
+} from './credentials.js';
 export { loginWithOAuth, StoredCredentialProvider } from './oauth.js';
 export type { OAuthLoginOptions } from './oauth.js';
 export {
@@ -35,6 +40,9 @@ export type {
   ProjectionRebuildResult,
 } from './service.js';
 export { defaultConfig, resolveHome } from './config.js';
+export { cloudApiUrl, SYNOMEM_CLOUD_API_URL } from './cloud.js';
+export { discoverBoundWorkspace, discoverOrganizations, workspaceChoices } from './discover.js';
+export type { DiscoveredOrganization, DiscoveredWorkspace, DiscoveryOptions } from './discover.js';
 export { asSynomemError, errorCodes, SynomemError } from './errors.js';
 export {
   dueInstant,

package/src/mcp/index.ts

@@ -6,6 +6,7 @@ import { configuredServiceFactory } from '../backend.js';
 import { SynomemError, asSynomemError } from '../errors.js';
 import {
   actorSchema,
+  agentHandleSchema,
   agentIdSchema,
   changesInputSchema,
   createNoteSchema,
@@ -88,9 +89,18 @@ export async function createSynomemMcpServer(
   options: SynomemMcpOptions,
   serviceFactory: SynomemServiceFactory = configuredServiceFactory,
 ): Promise<SynomemMcpRuntime> {
-  const actor = actorSchema.parse(options.actor);
-  const client = serviceFactory({ ...options, actor });
+  const requested = actorSchema.parse(options.actor);
+  const client = serviceFactory({ ...options, actor: requested });
   await client.init();
+  /*
+   * Every tool reports the CANONICAL actor, not the one that was asked for.
+   *
+   * A harness registers with a handle because that is what a person typed, but
+   * init resolves it against stored state — so the identity echoed back is the
+   * one the events will actually carry. Reporting the requested name would let
+   * a misconfigured runtime appear to be acting as somebody it is not.
+   */
+  const actor = client.actor;
   const server = new McpServer(
     { name: 'synomem', version: packageVersion() },
     {
@@ -282,9 +292,9 @@ export async function createSynomemMcpServer(
       description:
         'Administrative tool for creating a stable agent identity. Disabled by default so runtime agents cannot silently create identities.',
       inputSchema: z.object({
-        id: agentIdSchema,
+        handle: agentHandleSchema,
         displayName: z.string().trim().min(1).max(200),
-        aliases: z.array(agentIdSchema).max(50).optional(),
+        aliases: z.array(agentHandleSchema).max(50).optional(),
         description: z.string().trim().max(2000).optional(),
       }),
       outputSchema,
@@ -300,7 +310,11 @@ export async function createSynomemMcpServer(
           );
         }
         const profile = await client.agents.create(input);
-        return success(actor, `Created agent ${profile.displayName} (${profile.id}).`, { profile });
+        return success(
+          actor,
+          `Created agent ${profile.displayName}: handle ${profile.handle}, ID ${profile.id}.`,
+          { profile },
+        );
       } catch (error) {
         return failure(actor, error);
       }

package/src/oauth.ts

@@ -207,7 +207,14 @@ export class StoredCredentialProvider implements SynomemCredentialProvider {
   async getAccessToken(signal?: AbortSignal): Promise<string | undefined> {
     if (this.env.SYNOMEM_ACCESS_TOKEN) return this.env.SYNOMEM_ACCESS_TOKEN;
     if (!this.loaded) {
-      this.credential = await this.store.get(this.reference);
+      const stored = await this.store.get(this.reference);
+      /*
+       * An installation key is not an OAuth credential: it cannot be refreshed
+       * and has no client or token endpoint. Treating one as OAuth would mean
+       * trying to renew something that never renews that way, so this path
+       * ignores it and lets the installation-key path handle it.
+       */
+      this.credential = stored && 'kind' in stored ? undefined : stored;
       this.loaded = true;
     }
     const credential = this.credential;

package/src/projections.ts

@@ -550,7 +550,7 @@ export class ProjectionManager implements ProjectionWriter {
     const generated: string[] = [];
 
     for (const profile of profiles) {
-      const agentDirectory = join(this.storage.home, profile.id);
+      const agentDirectory = join(this.storage.home, profile.handle);
       assertNoSymlinkEscape(this.storage.home, agentDirectory);
       ensureDirectory(agentDirectory);
       const profilePath = join(agentDirectory, 'profile.json');
@@ -656,7 +656,7 @@ export class ProjectionManager implements ProjectionWriter {
       (record) => record.event.assigneeAgentId === profile.id,
     );
     const rebuiltAt = events.at(-1)?.createdAt ?? new Date(0).toISOString();
-    const agentDirectory = join(this.storage.home, profile.id);
+    const agentDirectory = join(this.storage.home, profile.handle);
     const inboxDirectory = join(agentDirectory, 'inbox');
     const kudosInboxDirectory = join(inboxDirectory, 'kudos');
     const memoInboxDirectory = join(inboxDirectory, 'memos');
@@ -729,7 +729,7 @@ export class ProjectionManager implements ProjectionWriter {
     }
 
     const keep = new Set(generated);
-    const prefixes = [`${profile.id}/`, `${profile.id}\\`];
+    const prefixes = [`${profile.handle}/`, `${profile.handle}\\`];
     const removed: string[] = [];
     for (const stale of this.storage
       .projectionManifest()
@@ -745,10 +745,18 @@ export class ProjectionManager implements ProjectionWriter {
       unlinkSync(path);
       removed.push(stale);
     }
-    this.storage.replaceAgentProjectionManifest(profile.id, generated, rebuiltAt);
+    this.storage.replaceAgentProjectionManifest(profile.handle, generated, rebuiltAt);
     return { generated: generated.sort(), removed: removed.sort() };
   }
 
+  /*
+   * The paths a rebuild would produce, for comparison against the manifest.
+   *
+   * Directories are named by HANDLE, matching what the writers above create,
+   * while the record filters match on the canonical agent ID, which is what
+   * stored events carry. Mixing the two up makes the comparison never agree,
+   * and `doctor` then reports every workspace's projections as stale forever.
+   */
   expectedPaths(): string[] {
     const profiles = this.storage.listAgents();
     const events = this.storage.getReadableEvents();
@@ -757,10 +765,12 @@ export class ProjectionManager implements ProjectionWriter {
     const tasks = taskRecordsFromEvents(events);
     const paths: string[] = [];
     for (const profile of profiles) {
-      paths.push(`${profile.id}/profile.json`);
-      if (this.storage.config.projection.writeWinsMarkdown) paths.push(`${profile.id}/WINS.md`);
-      if (this.storage.config.projection.writeMemoryMarkdown) paths.push(`${profile.id}/MEMORY.md`);
-      if (this.storage.config.projection.writeTasksMarkdown) paths.push(`${profile.id}/TASKS.md`);
+      paths.push(`${profile.handle}/profile.json`);
+      if (this.storage.config.projection.writeWinsMarkdown) paths.push(`${profile.handle}/WINS.md`);
+      if (this.storage.config.projection.writeMemoryMarkdown)
+        paths.push(`${profile.handle}/MEMORY.md`);
+      if (this.storage.config.projection.writeTasksMarkdown)
+        paths.push(`${profile.handle}/TASKS.md`);
       if (this.storage.config.projection.writeInboxEntries) {
         for (const record of records.filter(
           (item) =>
@@ -768,19 +778,19 @@ export class ProjectionManager implements ProjectionWriter {
             item.status === 'unacknowledged' &&
             item.revocationStatus === 'active',
         )) {
-          paths.push(`${profile.id}/inbox/kudos/${record.event.id}.md`);
+          paths.push(`${profile.handle}/inbox/kudos/${record.event.id}.md`);
         }
         for (const record of memos.filter(
           (item) => item.event.recipientAgentId === profile.id && item.status === 'unread',
         )) {
-          paths.push(`${profile.id}/inbox/memos/${record.event.id}.md`);
+          paths.push(`${profile.handle}/inbox/memos/${record.event.id}.md`);
         }
         for (const record of tasks.filter(
           (item) =>
             item.event.assigneeAgentId === profile.id &&
             (item.status === 'open' || item.status === 'assigned'),
         )) {
-          paths.push(`${profile.id}/inbox/tasks/${record.event.id}.md`);
+          paths.push(`${profile.handle}/inbox/tasks/${record.event.id}.md`);
         }
       }
     }

package/src/prompt.ts

@@ -0,0 +1,88 @@
+/**
+ * A small prompt boundary, injectable so the wizard is testable.
+ *
+ * Deliberately not a dependency: the wizard needs a select, a line, a masked
+ * line and a confirm, and a library for that would be more surface than
+ * substance. Everything reads from an injected stream, so tests drive the flow
+ * without a terminal.
+ */
+import { createInterface } from 'node:readline/promises';
+import type { Readable, Writable } from 'node:stream';
+
+export interface PromptIo {
+  input: Readable;
+  output: Writable;
+  /**
+   * Whether a person is actually there. A wizard must never wait forever on a
+   * pipe, so a non-interactive stream is refused with instructions instead.
+   */
+  interactive: boolean;
+}
+
+export function defaultPromptIo(): PromptIo {
+  return {
+    input: process.stdin,
+    output: process.stdout,
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+  };
+}
+
+async function readLine(io: PromptIo, question: string): Promise<string> {
+  const rl = createInterface({ input: io.input, output: io.output, terminal: io.interactive });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+export async function ask(io: PromptIo, question: string, fallback?: string): Promise<string> {
+  const suffix = fallback ? ` [${fallback}]` : '';
+  const answer = await readLine(io, `${question}${suffix}: `);
+  return answer || fallback || '';
+}
+
+export async function confirm(io: PromptIo, question: string): Promise<boolean> {
+  const answer = await readLine(io, `${question} [y/N]: `);
+  return /^y(es)?$/i.test(answer);
+}
+
+/**
+ * Reads a secret from a non-interactive stream, or prompts for one.
+ *
+ * Piping a secret in is the SAFE path and is why this accepts a closed stream
+ * rather than refusing it: a token passed as a command-line argument is kept by
+ * both the shell history and the process list, so `--access-token-stdin` has to
+ * work without a terminal.
+ */
+export async function askSecret(io: PromptIo, question: string): Promise<string> {
+  if (!io.interactive) {
+    const chunks: Buffer[] = [];
+    for await (const chunk of io.input) chunks.push(Buffer.from(chunk as Uint8Array));
+    return Buffer.concat(chunks).toString('utf8').trim();
+  }
+  // Readline echoes, so an interactive secret is read the same way and the
+  // caller is told not to expect masking rather than being silently exposed.
+  io.output.write('The value you type will be visible. Paste it, or pipe it in instead.\n');
+  return await readLine(io, `${question}: `);
+}
+
+export async function select<T extends string>(
+  io: PromptIo,
+  question: string,
+  choices: Array<{ value: T; label: string; detail?: string }>,
+): Promise<T> {
+  io.output.write(`\n${question}\n\n`);
+  choices.forEach((choice, index) => {
+    io.output.write(`  ${index + 1}) ${choice.label}\n`);
+    if (choice.detail) io.output.write(`     ${choice.detail}\n`);
+  });
+  io.output.write('\n');
+  for (;;) {
+    const answer = await readLine(io, `Choose 1-${choices.length} [1]: `);
+    const index = Number(answer || '1');
+    const choice = choices[index - 1];
+    if (choice) return choice.value;
+    io.output.write('Enter one of the listed numbers.\n');
+  }
+}

package/src/remote.ts

@@ -179,6 +179,30 @@ export class RemoteSynomemService implements SynomemService {
         'GET',
         `agents/resolve?query=${encodeURIComponent(query)}`,
       ),
+    archive: (idOrAlias: string) =>
+      this.mutation<Awaited<ReturnType<SynomemService['agents']['archive']>>>(
+        'POST',
+        `agents/${encodeURIComponent(idOrAlias)}/archive`,
+        {},
+      ),
+    restore: (idOrAlias: string) =>
+      this.mutation<Awaited<ReturnType<SynomemService['agents']['restore']>>>(
+        'POST',
+        `agents/${encodeURIComponent(idOrAlias)}/restore`,
+        {},
+      ),
+    addAliases: (idOrAlias: string, aliases: string[]) =>
+      this.mutation<Awaited<ReturnType<SynomemService['agents']['addAliases']>>>(
+        'POST',
+        `agents/${encodeURIComponent(idOrAlias)}/aliases`,
+        { aliases },
+      ),
+    removeAliases: (idOrAlias: string, aliases: string[]) =>
+      this.mutation<Awaited<ReturnType<SynomemService['agents']['removeAliases']>>>(
+        'POST',
+        `agents/${encodeURIComponent(idOrAlias)}/aliases/remove`,
+        { aliases },
+      ),
     directory: () =>
       this.request<Awaited<ReturnType<SynomemService['agents']['directory']>>>(
         'GET',

package/src/schemas.ts

@@ -17,12 +17,34 @@ const reservedIds = new Set([
   'lpt1',
 ]);
 
-export const agentIdSchema = z
+/**
+ * A handle: the human-friendly name for an agent, unique within its workspace.
+ *
+ * Mutable, unlike the canonical ID. People and agents type this, so it stays
+ * lowercase kebab and refuses the reserved words that would collide with
+ * filesystem or route segments.
+ */
+export const agentHandleSchema = z
   .string()
   .min(1)
   .max(63)
   .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'Use lowercase ASCII letters, digits, and hyphens')
-  .refine((id) => !reservedIds.has(id), 'Reserved agent ID');
+  .refine((handle) => !reservedIds.has(handle), 'Reserved agent handle');
+
+/** A canonical opaque agent ID: a ULID, uppercase Crockford base32. */
+export const agentUlidSchema = z.string().regex(/^[0-9A-HJKMNP-TV-Z]{26}$/);
+
+/**
+ * An actor ID as it appears in an event.
+ *
+ * Accepts a ULID or a handle-shaped name. New agents are created with an opaque
+ * ULID so a handle can be renamed without orphaning the events that reference
+ * the actor; agents that predate that, and human and system actors, carry a
+ * name-shaped ID. Widening rather than replacing keeps append-only history
+ * readable — rewriting the actor ID inside stored events to tidy the format
+ * would be exactly the rewrite the event log exists to prevent.
+ */
+export const agentIdSchema = z.union([agentUlidSchema, agentHandleSchema]);
 
 /**
  * An alias as written, folded to the canonical lowercase form.
@@ -110,16 +132,42 @@ export const evidenceSchema = z
   });
 
 export const profileSchema = z.object({
+  /** Canonical, opaque and immutable. Events reference this, never the handle. */
   id: agentIdSchema,
+  handle: agentHandleSchema,
   displayName: z.string().trim().min(1).max(200),
   aliases: z.array(agentAliasSchema).max(50).optional(),
   description: z.string().trim().max(2000).optional(),
+  /** Archived agents keep their history and stop being able to act. */
+  status: z.enum(['active', 'archived']).default('active'),
   createdAt: z.string().datetime({ offset: true }),
   metadata: metadataSchema.optional(),
 });
 
-export const createAgentSchema = profileSchema.omit({ createdAt: true });
-export const updateAgentSchema = createAgentSchema.omit({ id: true }).partial();
+/**
+ * Creating an agent names a handle; the canonical ID is generated, never
+ * supplied. A caller that could choose the ID could choose one that collides
+ * with an archived agent's history.
+ */
+export const createAgentSchema = z
+  .object({
+    handle: agentHandleSchema,
+    displayName: z.string().trim().min(1).max(200),
+    aliases: z.array(agentAliasSchema).max(50).optional(),
+    description: z.string().trim().max(2000).optional(),
+    metadata: metadataSchema.optional(),
+  })
+  .strict();
+
+export const updateAgentSchema = z
+  .object({
+    handle: agentHandleSchema.optional(),
+    displayName: z.string().trim().min(1).max(200).optional(),
+    aliases: z.array(agentAliasSchema).max(50).optional(),
+    description: z.string().trim().max(2000).optional(),
+    metadata: metadataSchema.optional(),
+  })
+  .strict();
 
 /**
  * A runtime binding is a claim about where an agent runs, so the fields stay
@@ -196,7 +244,14 @@ const agentCreatedSchema = baseEventSchema.extend({
 const agentUpdatedSchema = baseEventSchema.extend({
   type: z.literal('agent.updated'),
   agentId: agentIdSchema,
-  changes: updateAgentSchema,
+  /*
+   * Archiving is recorded as an update, so `status` belongs in the event even
+   * though callers cannot set it through `agents.update` — it moves through
+   * `archive` and `restore`, which keep the transition explicit.
+   */
+  changes: updateAgentSchema.extend({
+    status: z.enum(['active', 'archived']).optional(),
+  }),
 });
 
 const memoSentSchema = baseEventSchema.extend({

package/src/service.ts

@@ -19,6 +19,7 @@ import type {
   CreateTodoResult,
   CreateTaskResult,
   DoctorResult,
+  ProjectionStatus,
   GiveKudosInput,
   GiveKudosResult,
   ItemListInput,
@@ -79,6 +80,10 @@ export interface SynomemDomainService {
     get(idOrAlias: string): Promise<AgentProfile>;
     list(): Promise<AgentProfile[]>;
     resolve(query: string): Promise<AgentResolution>;
+    archive(idOrAlias: string): Promise<AgentProfile>;
+    restore(idOrAlias: string): Promise<AgentProfile>;
+    addAliases(idOrAlias: string, aliases: string[]): Promise<AgentProfile>;
+    removeAliases(idOrAlias: string, aliases: string[]): Promise<AgentProfile>;
     directory(): Promise<AgentDirectoryEntry[]>;
     bindings(idOrAlias: string): Promise<AgentRuntimeBinding[]>;
     bindRuntime(input: BindRuntimeInput): Promise<AgentRuntimeBinding>;
@@ -209,6 +214,13 @@ export interface SynomemService extends SynomemDomainService {
   doctor(): Promise<DoctorResult>;
   export(format: 'json' | 'jsonl' | 'markdown'): Promise<string>;
   backup?(destination: string): Promise<string>;
+  /*
+   * Optional, because only a backend that writes projected files can report on
+   * them. The remote backend keeps no filesystem projections at all, and
+   * inventing an empty answer there would read as "nothing is stale" rather
+   * than "there is nothing to be stale".
+   */
+  projectionStatus?(): Promise<ProjectionStatus>;
   rebuild(): Promise<ProjectionRebuildResult>;
   capabilities(): Promise<SynomemServiceCapabilities>;
   info(): Promise<SynomemServiceInfo>;