synomem 0.3.0 → 0.4.0

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

@@ -79,6 +79,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>;

package/src/storage.ts

@@ -255,6 +255,21 @@ CREATE TABLE post_acknowledgments (
 CREATE INDEX post_acknowledgments_post ON post_acknowledgments(post_id);
 `;
 
+const migrationV7 = `
+-- Opaque canonical IDs, with the handle as a separate mutable name.
+--
+-- Existing agents keep their name-shaped ID and take it as their handle too.
+-- Rewriting the actor ID inside stored events to tidy the format would be
+-- exactly the rewrite an append-only log exists to prevent, so history stays
+-- as written and only NEW agents get a generated opaque ID.
+ALTER TABLE agents ADD COLUMN handle TEXT;
+UPDATE agents SET handle = id WHERE handle IS NULL;
+CREATE UNIQUE INDEX agents_handle ON agents(handle);
+
+-- Archived agents keep their records and stop being able to act.
+ALTER TABLE agents ADD COLUMN status TEXT NOT NULL DEFAULT 'active';
+`;
+
 const migrationV3 = `
 DROP TRIGGER IF EXISTS events_append_only_update;
 DROP TRIGGER IF EXISTS events_append_only_delete;
@@ -430,7 +445,8 @@ export class SynomemStorage implements SynomemRepository {
 
   constructor(options: StorageOptions) {
     this.home = resolve(options.home);
-    this.storageDirectory = join(this.home, 'synomem');
+    // The home is the storage directory; see configLocation in backend.ts.
+    this.storageDirectory = this.home;
     this.databasePath = join(this.storageDirectory, 'synomem.sqlite3');
     this.configPath = join(this.storageDirectory, 'config.json');
     this.readOnly = options.readOnly;
@@ -518,7 +534,7 @@ export class SynomemStorage implements SynomemRepository {
     const version = Number(
       (db.prepare('PRAGMA user_version').get() as { user_version: number }).user_version,
     );
-    if (version > 6) {
+    if (version > 7) {
       throw new SynomemError(
         'UNSUPPORTED_SCHEMA',
         `Database schema version ${version} is newer than this package supports.`,
@@ -598,14 +614,26 @@ export class SynomemStorage implements SynomemRepository {
         db.exec('PRAGMA user_version = 6');
       });
     }
+    const afterV6 = Number(
+      (db.prepare('PRAGMA user_version').get() as { user_version: number }).user_version,
+    );
+    if (afterV6 === 6) {
+      this.transactionSync(() => {
+        db.exec(migrationV7);
+        db.prepare(
+          'INSERT OR IGNORE INTO schema_migrations(version, applied_at) VALUES (?, ?)',
+        ).run(7, new Date().toISOString());
+        db.exec('PRAGMA user_version = 7');
+      });
+    }
   }
 
   private assertSchemaSupported(): void {
     const version = Number(
       (this.db().prepare('PRAGMA user_version').get() as { user_version: number }).user_version,
     );
-    if (version !== 6) {
-      if (version >= 1 && version <= 5) {
+    if (version !== 7) {
+      if (version >= 1 && version <= 6) {
         throw new SynomemError(
           'UNSUPPORTED_SCHEMA',
           `Database schema version ${version} requires migration. Open this home once with readOnly: false, then retry the read-only client.`,
@@ -1530,12 +1558,23 @@ export class SynomemStorage implements SynomemRepository {
     return { schemaVersion, appliedVersions };
   }
 
+  /**
+   * Aliases that also name an agent directly.
+   *
+   * Matches against the HANDLE as well as the canonical ID. With opaque IDs an
+   * alias can no longer accidentally equal one, but it can easily equal another
+   * agent's handle — which is the collision that actually makes a lookup
+   * ambiguous now.
+   */
   aliasIdentityConflicts(): Array<{ alias: string; agentId: string }> {
     return this.db()
       .prepare(
         `SELECT x.alias, x.agent_id AS agentId
-         FROM aliases x JOIN agents a ON a.id = x.alias
-         ORDER BY x.alias`,
+         FROM aliases x
+         JOIN agents a ON lower(a.id) = x.normalized_alias
+                       OR lower(a.handle) = x.normalized_alias
+        WHERE a.id != x.agent_id
+        ORDER BY x.alias`,
       )
       .all() as unknown as Array<{ alias: string; agentId: string }>;
   }
@@ -1727,10 +1766,13 @@ export class SynomemStorage implements SynomemRepository {
     const parsed = profileSchema.parse(profile);
     this.db()
       .prepare(
-        'INSERT INTO agents(id, display_name, profile_json, created_at, updated_at) VALUES (?, ?, ?, ?, ?)',
+        `INSERT INTO agents(id, handle, status, display_name, profile_json, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
       )
       .run(
         parsed.id,
+        parsed.handle,
+        parsed.status,
         parsed.displayName,
         JSON.stringify(parsed),
         parsed.createdAt,
@@ -1742,8 +1784,18 @@ export class SynomemStorage implements SynomemRepository {
   updateAgent(profile: AgentProfile, updatedAt: string): void {
     const parsed = profileSchema.parse(profile);
     this.db()
-      .prepare('UPDATE agents SET display_name = ?, profile_json = ?, updated_at = ? WHERE id = ?')
-      .run(parsed.displayName, JSON.stringify(parsed), updatedAt, parsed.id);
+      .prepare(
+        `UPDATE agents SET handle = ?, status = ?, display_name = ?, profile_json = ?,
+           updated_at = ? WHERE id = ?`,
+      )
+      .run(
+        parsed.handle,
+        parsed.status,
+        parsed.displayName,
+        JSON.stringify(parsed),
+        updatedAt,
+        parsed.id,
+      );
     this.db().prepare('DELETE FROM aliases WHERE agent_id = ?').run(parsed.id);
     this.insertAliases(parsed.id, parsed.aliases ?? []);
   }
@@ -1770,10 +1822,10 @@ export class SynomemStorage implements SynomemRepository {
         `SELECT DISTINCT a.profile_json
            FROM agents a
            LEFT JOIN aliases x ON x.agent_id = a.id
-          WHERE lower(a.id) = ? OR x.normalized_alias = ?
+          WHERE lower(a.id) = ? OR lower(a.handle) = ? OR x.normalized_alias = ?
           ORDER BY a.id ASC`,
       )
-      .all(normalized, normalized) as unknown as ProfileRow[];
+      .all(normalized, normalized, normalized) as unknown as ProfileRow[];
     const candidates = rows.map((row) => profileSchema.parse(JSON.parse(row.profile_json)));
     return candidates.length === 1 ? { match: candidates[0]!, candidates } : { candidates };
   }
@@ -1964,11 +2016,16 @@ export class SynomemStorage implements SynomemRepository {
     });
   }
 
-  replaceAgentProjectionManifest(agentId: string, paths: string[], generatedAt: string): void {
+  /**
+   * @param directory the agent's projection directory name, which is its
+   * handle rather than its canonical ID: these rows are keyed by the path on
+   * disk, and projections are named for people to read.
+   */
+  replaceAgentProjectionManifest(directory: string, paths: string[], generatedAt: string): void {
     this.transactionSync(() => {
       this.db()
         .prepare('DELETE FROM projection_manifest WHERE path LIKE ? OR path LIKE ?')
-        .run(`${agentId}/%`, `${agentId}\\%`);
+        .run(`${directory}/%`, `${directory}\\%`);
       const insert = this.db().prepare(
         'INSERT INTO projection_manifest(path, generated_at) VALUES (?, ?)',
       );

package/src/types.ts

@@ -28,10 +28,22 @@ export interface EvidenceReference {
 }
 
 export interface AgentProfile {
+  /**
+   * Canonical, opaque, immutable. Every event references this, so it can never
+   * change — which is exactly why the handle exists separately.
+   */
   id: string;
+  /** The human-friendly name, unique in the workspace and safe to rename. */
+  handle: string;
   displayName: string;
   aliases?: string[];
   description?: string;
+  /**
+   * Archived agents keep their history and stop being able to act. Events
+   * reference the actor permanently, so deletion would leave history pointing
+   * at nothing.
+   */
+  status: 'active' | 'archived';
   createdAt: string;
   metadata?: Record<string, JsonValue>;
 }
@@ -684,13 +696,15 @@ export interface BindRuntimeInput {
 }
 
 export interface CreateAgentInput {
-  id: string;
+  /** The handle. The canonical ID is generated, never supplied. */
+  handle: string;
   displayName: string;
   aliases?: string[];
   description?: string;
   metadata?: Record<string, JsonValue>;
 }
 export interface UpdateAgentInput {
+  handle?: string;
   displayName?: string;
   aliases?: string[];
   description?: string;
@@ -706,7 +720,15 @@ export interface KudosStats {
   byTag: Record<string, number>;
 }
 export interface Diagnostic {
-  level: 'ok' | 'warning' | 'error';
+  /**
+   * `skipped` is not a failure.
+   *
+   * A check the caller lacks permission to run says so and leaves the overall
+   * result healthy. Failing the whole diagnostic because an ordinary agent
+   * cannot read workspace administration would make `doctor` useless to the
+   * callers who need it most.
+   */
+  level: 'ok' | 'warning' | 'error' | 'skipped';
   code: string;
   message: string;
   path?: string;