synomem 0.2.0 → 0.4.0

package/src/client.ts

@@ -8,6 +8,7 @@ import {
   escapeMarkdown,
   memoRecordsFromEvents,
   noteRecordsFromEvents,
+  postRecordsFromEvents,
   ProjectionManager,
   recordsFromEvents,
   taskRecordsFromEvents,
@@ -18,6 +19,8 @@ import {
   agentLookupSchema,
   bindRuntimeSchema,
   createAgentSchema,
+  createPostSchema,
+  updatePostSchema,
   createNoteSchema,
   createTaskSchema,
   createTodoSchema,
@@ -49,6 +52,10 @@ import type {
   AgentRuntimeBinding,
   BindRuntimeInput,
   CreateAgentInput,
+  CreatePostInput,
+  PostRecord,
+  PostRoster,
+  UpdatePostInput,
   Diagnostic,
   DoctorResult,
   GiveKudosInput,
@@ -99,7 +106,11 @@ export interface SynomemCoreOptions {
 }
 
 export class SynomemCore implements SynomemDomainService {
-  readonly actor: ActorIdentity;
+  /**
+   * Mutable because an agent actor is resolved to its canonical identity on
+   * init: callers name a handle, events record the opaque ID.
+   */
+  actor: ActorIdentity;
   private readonly repository: SynomemRepository;
   private readonly projectionWriter: ProjectionWriter;
   private readonly clock: () => Date;
@@ -114,6 +125,11 @@ export class SynomemCore implements SynomemDomainService {
     get: (idOrAlias: string) => this.getAgent(idOrAlias),
     list: () => this.listAgents(),
     resolve: (query: string) => this.resolveAgent(query),
+    archive: (idOrAlias: string) => this.setAgentStatus(idOrAlias, 'archived'),
+    restore: (idOrAlias: string) => this.setAgentStatus(idOrAlias, 'active'),
+    addAliases: (idOrAlias: string, aliases: string[]) => this.addAgentAliases(idOrAlias, aliases),
+    removeAliases: (idOrAlias: string, aliases: string[]) =>
+      this.removeAgentAliases(idOrAlias, aliases),
     directory: () => this.agentDirectory(),
     bindings: (idOrAlias: string) => this.listRuntimeBindings(idOrAlias),
     bindRuntime: (input: BindRuntimeInput) => this.bindRuntime(input),
@@ -139,6 +155,27 @@ export class SynomemCore implements SynomemDomainService {
     archive: (input: { memoId: string; idempotencyKey?: string }) => this.archiveMemo(input),
   };
 
+  readonly posts = {
+    create: (input: CreatePostInput) => this.createPost(input),
+    list: (input: Omit<ItemListInput, 'kinds'> = {}) =>
+      this.listItems({ ...input, kinds: ['post'] }),
+    get: (id: string) => this.getPost(id),
+    update: (input: UpdatePostInput) => this.updatePost(input),
+    archive: (input: { postId: string; reason?: string; idempotencyKey?: string }) =>
+      this.archivePost(input),
+    /*
+     * Acknowledging is an explicit call and always speaks for the caller alone.
+     * There is no bulk form and no acknowledge-on-behalf-of: an acknowledgement
+     * is one actor saying "I have seen this", and reading a post must never
+     * append one, or the roster stops meaning anything.
+     */
+    acknowledge: (input: { postId: string; note?: string; idempotencyKey?: string }) =>
+      this.acknowledgePost(input),
+    withdrawAcknowledgment: (input: { postId: string; reason?: string }) =>
+      this.withdrawPostAcknowledgment(input),
+    roster: (postId: string) => this.postRoster(postId),
+  };
+
   readonly notes = {
     create: (input: CreateNoteInput) => this.createNote(input),
     list: (input: Omit<ItemListInput, 'kinds'> = {}) =>
@@ -243,6 +280,30 @@ export class SynomemCore implements SynomemDomainService {
     if (this.initialized) return;
     await this.repository.init();
     this.initialized = true;
+
+    /*
+     * An agent actor is resolved to its canonical identity here.
+     *
+     * Callers name a handle because that is what people and harnesses know,
+     * but every event must record the opaque ID — otherwise renaming a handle
+     * would orphan the history written under the old one. The display name
+     * comes from the profile for the same reason a harness cannot assert it on
+     * the command line: the stored record is the authority, not the argument.
+     *
+     * An unresolvable name is left as given rather than rejected, so a system
+     * actor can still create the agent that does not exist yet. Writing as an
+     * unknown agent is refused later by the checks that already exist.
+     */
+    if (this.actor.kind === 'agent') {
+      const resolved = await this.repository.resolveAgent(this.actor.id);
+      if (resolved.match) {
+        this.actor = {
+          kind: 'agent',
+          id: resolved.match.id,
+          ...(resolved.match.displayName ? { displayName: resolved.match.displayName } : {}),
+        };
+      }
+    }
   }
 
   async close(): Promise<void> {
@@ -286,20 +347,29 @@ export class SynomemCore implements SynomemDomainService {
     this.checkAbort();
     await this.repository.assertEventCompatibility();
     const parsed = this.validate(() => createAgentSchema.parse(input));
-    if (await this.repository.getAgent(parsed.id)) {
-      throw new SynomemError('AGENT_EXISTS', `Agent or alias already exists: ${parsed.id}`);
+    if (await this.repository.getAgent(parsed.handle)) {
+      throw new SynomemError('AGENT_EXISTS', `Agent or alias already exists: ${parsed.handle}`);
     }
     const aliases = [...new Set(parsed.aliases ?? [])].sort();
-    if (aliases.includes(parsed.id)) {
-      throw new SynomemError('ALIAS_CONFLICT', 'An agent cannot use its own ID as an alias.');
+    if (aliases.includes(parsed.handle)) {
+      throw new SynomemError('ALIAS_CONFLICT', 'An agent cannot use its own handle as an alias.');
     }
     for (const alias of aliases) {
       if (await this.repository.getAgent(alias)) {
         throw new SynomemError('ALIAS_CONFLICT', `Alias already belongs to an agent: ${alias}`);
       }
     }
+    /*
+     * The canonical ID is generated here and never supplied by the caller.
+     * Every event references it permanently, so it has to be free of meaning:
+     * a caller that could choose it could choose one that collides with an
+     * archived agent's history, and a meaningful ID becomes a handle nobody can
+     * rename.
+     */
     const profile: AgentProfile = {
-      id: parsed.id,
+      id: this.nextId(),
+      handle: parsed.handle,
+      status: 'active',
       displayName: parsed.displayName,
       ...(aliases.length ? { aliases } : {}),
       ...(parsed.description !== undefined ? { description: parsed.description } : {}),
@@ -327,8 +397,20 @@ export class SynomemCore implements SynomemDomainService {
     const existing = await this.repository.getAgent(idOrAlias);
     if (!existing) throw new SynomemError('AGENT_NOT_FOUND', `Unknown agent: ${idOrAlias}`);
     const aliases = parsed.aliases ? [...new Set(parsed.aliases)].sort() : existing.aliases;
-    if (aliases?.includes(existing.id)) {
-      throw new SynomemError('ALIAS_CONFLICT', 'An agent cannot use its own ID as an alias.');
+    const handle = parsed.handle ?? existing.handle;
+    if (aliases?.includes(handle)) {
+      throw new SynomemError('ALIAS_CONFLICT', 'An agent cannot use its own handle as an alias.');
+    }
+    // Renaming the handle is allowed and is why the canonical ID exists, but a
+    // handle another agent already answers to is still refused.
+    if (parsed.handle && parsed.handle !== existing.handle) {
+      const owner = await this.repository.getAgent(parsed.handle);
+      if (owner && owner.id !== existing.id) {
+        throw new SynomemError(
+          'ALIAS_CONFLICT',
+          `Handle already belongs to ${owner.id}: ${parsed.handle}`,
+        );
+      }
     }
     for (const alias of aliases ?? []) {
       const owner = await this.repository.getAgent(alias);
@@ -356,6 +438,52 @@ export class SynomemCore implements SynomemDomainService {
     return updated;
   }
 
+  /**
+   * Archiving stops an agent acting without erasing it.
+   *
+   * Events reference the actor permanently, so deleting an agent would leave
+   * history pointing at nothing. Archived agents keep their records and their
+   * handle, and can be restored.
+   */
+  private async setAgentStatus(
+    idOrAlias: string,
+    status: 'active' | 'archived',
+  ): Promise<AgentProfile> {
+    this.checkAbort();
+    await this.repository.assertEventCompatibility();
+    this.validate(() => agentLookupSchema.parse(idOrAlias));
+    const existing = await this.repository.getAgent(idOrAlias);
+    if (!existing) throw new SynomemError('AGENT_NOT_FOUND', `Unknown agent: ${idOrAlias}`);
+    if (existing.status === status) return existing;
+    const updated: AgentProfile = { ...existing, status };
+    await this.repository.transaction(async () => {
+      const event: SynomemEvent = {
+        ...this.eventBase(existing.id, await this.repository.nextAggregateVersion(existing.id)),
+        type: 'agent.updated',
+        agentId: existing.id,
+        changes: { status },
+      };
+      await this.repository.updateAgent(updated, event.createdAt);
+      await this.repository.insertEvent(event);
+    });
+    await this.projectionWriter.syncAgent(updated.id);
+    return updated;
+  }
+
+  /** Adds aliases without disturbing the ones already there. */
+  private async addAgentAliases(idOrAlias: string, add: string[]): Promise<AgentProfile> {
+    const existing = await this.getAgent(idOrAlias);
+    const merged = [...new Set([...(existing.aliases ?? []), ...add])].sort();
+    return await this.updateAgent(existing.id, { aliases: merged });
+  }
+
+  private async removeAgentAliases(idOrAlias: string, remove: string[]): Promise<AgentProfile> {
+    const existing = await this.getAgent(idOrAlias);
+    const drop = new Set(remove.map((alias) => alias.trim().toLowerCase()));
+    const kept = (existing.aliases ?? []).filter((alias) => !drop.has(alias));
+    return await this.updateAgent(existing.id, { aliases: kept });
+  }
+
   private async getAgent(idOrAlias: string): Promise<AgentProfile> {
     this.checkAbort();
     this.validate(() => agentLookupSchema.parse(idOrAlias));
@@ -757,6 +885,174 @@ export class SynomemCore implements SynomemDomainService {
     return await this.getMemoRecord(input.memoId);
   }
 
+  private async getPostRecord(id: string): Promise<PostRecord> {
+    await this.requireVisibleItem(id, 'post');
+    const record = postRecordsFromEvents(await this.repository.getReadableItemEvents(id))[0];
+    if (!record) throw new SynomemError('ITEM_NOT_FOUND', `Unknown post: ${id}`);
+    return record;
+  }
+
+  private async getPost(id: string): Promise<PostRecord> {
+    this.checkAbort();
+    return await this.getPostRecord(id);
+  }
+
+  private async createPost(input: CreatePostInput): Promise<{
+    record: PostRecord;
+    created: boolean;
+    deduplicated: boolean;
+  }> {
+    this.checkAbort();
+    await this.repository.assertEventCompatibility();
+    const parsed = this.validate(() => createPostSchema.parse(input));
+
+    // A reply inherits its parent's workspace by construction, and cannot name
+    // a different target — there is no target to name.
+    if (parsed.replyTo) await this.requireVisibleItem(parsed.replyTo, 'post');
+
+    const outcome = await this.repository.transaction(async () => {
+      const prior = await this.priorMutation(parsed.idempotencyKey, 'post.created');
+      if (prior?.type === 'post.created') return { id: prior.id, created: false };
+      const id = this.nextId();
+      const event: SynomemEvent = {
+        ...this.eventBase(id, 1, id),
+        type: 'post.created',
+        title: parsed.title,
+        body: parsed.body,
+        tags: [...new Set(parsed.tags ?? [])].sort(),
+        ...(parsed.replyTo ? { replyTo: parsed.replyTo } : {}),
+        ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
+        ...(parsed.source ? { source: parsed.source } : {}),
+        ...(parsed.metadata ? { metadata: parsed.metadata } : {}),
+      };
+      await this.repository.insertEvent(event);
+      return { id, created: true };
+    });
+    return {
+      record: await this.getPostRecord(outcome.id),
+      created: outcome.created,
+      deduplicated: !outcome.created,
+    };
+  }
+
+  /** Only the author edits a post. Everyone else responds to it. */
+  private assertPostAuthor(record: PostRecord): void {
+    if (this.administrative) return;
+    if (record.event.actor.id !== this.actor.id || record.event.actor.kind !== this.actor.kind) {
+      throw new SynomemError('MUTATION_FORBIDDEN', 'Only the author can change a post.');
+    }
+  }
+
+  private async updatePost(input: UpdatePostInput): Promise<PostRecord> {
+    this.checkAbort();
+    const parsed = this.validate(() => updatePostSchema.parse(input));
+    const record = await this.getPostRecord(parsed.postId);
+    this.assertPostAuthor(record);
+    if (record.status === 'archived') {
+      throw new SynomemError('MUTATION_FORBIDDEN', 'An archived post cannot be edited.');
+    }
+    if (record.version !== parsed.expectedVersion) {
+      throw new SynomemError(
+        'REVISION_CONFLICT',
+        `Post ${parsed.postId} is at version ${record.version}.`,
+      );
+    }
+    await this.repository.transaction(async () => {
+      const event: SynomemEvent = {
+        ...this.eventBase(parsed.postId, await this.repository.nextAggregateVersion(parsed.postId)),
+        type: 'post.edited',
+        postId: parsed.postId,
+        title: parsed.title ?? record.title,
+        body: parsed.body ?? record.body,
+        tags: [...new Set(parsed.tags ?? record.tags ?? [])].sort(),
+        ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
+      };
+      await this.repository.insertEvent(event);
+    });
+    return await this.getPostRecord(parsed.postId);
+  }
+
+  private async archivePost(input: {
+    postId: string;
+    reason?: string;
+    idempotencyKey?: string;
+  }): Promise<PostRecord> {
+    this.checkAbort();
+    const record = await this.getPostRecord(input.postId);
+    this.assertPostAuthor(record);
+    if (record.status !== 'archived') {
+      await this.repository.transaction(async () => {
+        const event: SynomemEvent = {
+          ...this.eventBase(input.postId, await this.repository.nextAggregateVersion(input.postId)),
+          type: 'post.archived',
+          postId: input.postId,
+          ...(input.reason ? { reason: input.reason } : {}),
+          ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+        };
+        await this.repository.insertEvent(event);
+      });
+    }
+    return await this.getPostRecord(input.postId);
+  }
+
+  private async acknowledgePost(input: {
+    postId: string;
+    note?: string;
+    idempotencyKey?: string;
+  }): Promise<PostRecord> {
+    this.checkAbort();
+    const record = await this.getPostRecord(input.postId);
+    // Acknowledging twice is the same statement, so the second is a no-op
+    // rather than a second row or an error.
+    const already = record.acknowledgments.some(
+      (entry) => entry.actor.id === this.actor.id && entry.actor.kind === this.actor.kind,
+    );
+    if (!already) {
+      await this.repository.transaction(async () => {
+        const event: SynomemEvent = {
+          ...this.eventBase(input.postId, await this.repository.nextAggregateVersion(input.postId)),
+          type: 'post.acknowledged',
+          postId: input.postId,
+          ...(input.note ? { note: input.note } : {}),
+          ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+        };
+        await this.repository.insertEvent(event);
+      });
+    }
+    return await this.getPostRecord(input.postId);
+  }
+
+  private async withdrawPostAcknowledgment(input: {
+    postId: string;
+    reason?: string;
+  }): Promise<PostRecord> {
+    this.checkAbort();
+    const record = await this.getPostRecord(input.postId);
+    const mine = record.acknowledgments.some(
+      (entry) => entry.actor.id === this.actor.id && entry.actor.kind === this.actor.kind,
+    );
+    if (mine) {
+      await this.repository.transaction(async () => {
+        const event: SynomemEvent = {
+          ...this.eventBase(input.postId, await this.repository.nextAggregateVersion(input.postId)),
+          type: 'post.acknowledgment.withdrawn',
+          postId: input.postId,
+          ...(input.reason ? { reason: input.reason } : {}),
+        };
+        await this.repository.insertEvent(event);
+      });
+    }
+    return await this.getPostRecord(input.postId);
+  }
+
+  private async postRoster(postId: string): Promise<PostRoster> {
+    this.checkAbort();
+    await this.requireVisibleItem(postId, 'post');
+    const roster = await this.repository.postRoster(postId);
+    if (!roster) throw new SynomemError('ITEM_NOT_FOUND', `Unknown post: ${postId}`);
+    return roster;
+  }
+
   private async getNoteRecord(id: string): Promise<NoteRecord> {
     await this.requireVisibleItem(id, 'note');
     const record = noteRecordsFromEvents(await this.repository.getReadableItemEvents(id))[0];
@@ -1245,10 +1541,34 @@ export class SynomemCore implements SynomemDomainService {
     return await this.getTodoRecord(input.todoId);
   }
 
+  /**
+   * Turns an agent name in a filter into the canonical ID the records hold.
+   *
+   * Callers filter by the name they know — a handle or an alias — while every
+   * record stores the opaque ID. Without this the filter silently matches
+   * nothing, which reads as "there is nothing here" rather than "that name
+   * means something else now".
+   *
+   * An unresolvable name is passed through unchanged so it can match a legacy
+   * name-shaped ID rather than being swallowed.
+   */
+  private async canonicalAgentId(name: string | undefined): Promise<string | undefined> {
+    if (!name) return name;
+    const resolved = await this.repository.resolveAgent(name);
+    return resolved.match?.id ?? name;
+  }
+
   private async listItems(input: ItemListInput): Promise<Page<ItemSummary>> {
     this.checkAbort();
     const parsed = this.validate(() => itemListInputSchema.parse(input));
-    return await this.repository.listItemSummaries(parsed, this.actor);
+    const resolved = {
+      ...parsed,
+      ...(parsed.participantAgentId
+        ? { participantAgentId: await this.canonicalAgentId(parsed.participantAgentId) }
+        : {}),
+      ...(parsed.actorId ? { actorId: await this.canonicalAgentId(parsed.actorId) } : {}),
+    };
+    return await this.repository.listItemSummaries(resolved, this.actor);
   }
   private async listItemChanges(input: ChangesInput): Promise<ChangePage> {
     this.checkAbort();
@@ -1343,8 +1663,8 @@ export class SynomemCore implements SynomemDomainService {
  * check that silently lags the migration runner reports a healthy database as
  * broken.
  */
-const CURRENT_SCHEMA_VERSION = 5;
-const EXPECTED_APPLIED_MIGRATIONS = [1, 2, 3, 4, 5];
+const CURRENT_SCHEMA_VERSION = 7;
+const EXPECTED_APPLIED_MIGRATIONS = [1, 2, 3, 4, 5, 6, 7];
 
 export class SynomemClient extends SynomemCore implements SynomemService {
   readonly home: string;

package/src/cloud.ts

@@ -0,0 +1,19 @@
+/**
+ * Synomem Cloud, as a constant rather than a question.
+ *
+ * Public onboarding must never ask for a service URL. A person setting up
+ * Synomem has no way to know whether an address they were given is the real
+ * one, and a prompt that accepts any origin is a prompt that can be phished.
+ * The hosted service therefore has one address, compiled in.
+ *
+ * `SYNOMEM_API_URL` remains for development and private deployments. It is
+ * deliberately undocumented in the README, the public docs, the packaged skill
+ * and ordinary help output — a private deployment is configured by whoever runs
+ * it, not discovered by an ordinary user.
+ */
+export const SYNOMEM_CLOUD_API_URL = 'https://api.synomem.ai';
+
+export function cloudApiUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.SYNOMEM_API_URL?.trim();
+  return override || SYNOMEM_CLOUD_API_URL;
+}

package/src/config.ts

@@ -73,7 +73,14 @@ export const configSchema = policySchema.extend({
 });
 
 export function resolveHome(explicitHome?: string): string {
-  const candidate = explicitHome ?? process.env.SYNOMEM_HOME ?? resolve(homedir(), '.agents');
+  /*
+   * `~/.synomem`, resolved as an exact directory.
+   *
+   * No detection of or migration from `~/.agents`: the project is greenfield,
+   * and code that quietly moves somebody's database is worse than a clear
+   * message telling them where the new home is.
+   */
+  const candidate = explicitHome ?? process.env.SYNOMEM_HOME ?? resolve(homedir(), '.synomem');
   if (candidate.includes('\0')) throw new SynomemError('UNSAFE_PATH', 'Storage home contains NUL.');
   return resolve(candidate);
 }