synomem 0.1.1 → 0.3.0

package/src/config.ts

@@ -10,14 +10,14 @@ export const defaultConfig: SynomemConfig = {
   workspaceId: 'workspace',
   defaultVisibility: 'workspace',
   allowSelfAwards: false,
-  allowCrossAgentTodos: true,
+  allowCrossAgentTasks: true,
   allowAgentCreationViaMcp: false,
   allowRebuildViaMcp: false,
   includePrivateInStats: false,
   projection: {
     writeWinsMarkdown: true,
     writeMemoryMarkdown: true,
-    writeTodosMarkdown: true,
+    writeTasksMarkdown: true,
     writeInboxEntries: true,
   },
 };
@@ -53,14 +53,14 @@ const policySchema = z.object({
   workspaceId: z.string().trim().min(1).max(100),
   defaultVisibility: z.enum(['private', 'workspace', 'public']),
   allowSelfAwards: z.boolean(),
-  allowCrossAgentTodos: z.boolean(),
+  allowCrossAgentTasks: z.boolean(),
   allowAgentCreationViaMcp: z.boolean(),
   allowRebuildViaMcp: z.boolean(),
   includePrivateInStats: z.boolean(),
   projection: z.object({
     writeWinsMarkdown: z.boolean(),
     writeMemoryMarkdown: z.boolean(),
-    writeTodosMarkdown: z.boolean(),
+    writeTasksMarkdown: z.boolean(),
     writeInboxEntries: z.boolean(),
   }),
 });
@@ -144,24 +144,24 @@ function environmentConfig(env: NodeJS.ProcessEnv): SynomemConfigOverrides {
 
   const writeWinsMarkdown = optionalBoolean(env, 'SYNOMEM_WRITE_WINS_MARKDOWN');
   const writeMemoryMarkdown = optionalBoolean(env, 'SYNOMEM_WRITE_MEMORY_MARKDOWN');
-  const writeTodosMarkdown = optionalBoolean(env, 'SYNOMEM_WRITE_TODOS_MARKDOWN');
+  const writeTasksMarkdown = optionalBoolean(env, 'SYNOMEM_WRITE_TASKS_MARKDOWN');
   const writeInboxEntries = optionalBoolean(env, 'SYNOMEM_WRITE_INBOX_ENTRIES');
   const allowSelfAwards = optionalBoolean(env, 'SYNOMEM_ALLOW_SELF_AWARDS');
-  const allowCrossAgentTodos = optionalBoolean(env, 'SYNOMEM_ALLOW_CROSS_AGENT_TODOS');
+  const allowCrossAgentTasks = optionalBoolean(env, 'SYNOMEM_ALLOW_CROSS_AGENT_TODOS');
   const allowAgentCreationViaMcp = optionalBoolean(env, 'SYNOMEM_ALLOW_AGENT_CREATION_VIA_MCP');
   const allowRebuildViaMcp = optionalBoolean(env, 'SYNOMEM_ALLOW_REBUILD_VIA_MCP');
   const includePrivateInStats = optionalBoolean(env, 'SYNOMEM_INCLUDE_PRIVATE_IN_STATS');
   const projection = {
     ...(writeWinsMarkdown !== undefined ? { writeWinsMarkdown } : {}),
     ...(writeMemoryMarkdown !== undefined ? { writeMemoryMarkdown } : {}),
-    ...(writeTodosMarkdown !== undefined ? { writeTodosMarkdown } : {}),
+    ...(writeTasksMarkdown !== undefined ? { writeTasksMarkdown } : {}),
     ...(writeInboxEntries !== undefined ? { writeInboxEntries } : {}),
   };
 
   return {
     ...(visibility ? { defaultVisibility: visibility as SynomemConfig['defaultVisibility'] } : {}),
     ...(allowSelfAwards !== undefined ? { allowSelfAwards } : {}),
-    ...(allowCrossAgentTodos !== undefined ? { allowCrossAgentTodos } : {}),
+    ...(allowCrossAgentTasks !== undefined ? { allowCrossAgentTasks } : {}),
     ...(allowAgentCreationViaMcp !== undefined ? { allowAgentCreationViaMcp } : {}),
     ...(allowRebuildViaMcp !== undefined ? { allowRebuildViaMcp } : {}),
     ...(includePrivateInStats !== undefined ? { includePrivateInStats } : {}),

package/src/index.ts

@@ -36,13 +36,22 @@ export type {
 } from './service.js';
 export { defaultConfig, resolveHome } from './config.js';
 export { asSynomemError, errorCodes, SynomemError } from './errors.js';
-export { escapeMarkdown, recordsFromEvents, renderMarkdownExport } from './projections.js';
+export {
+  dueInstant,
+  escapeMarkdown,
+  recordsFromEvents,
+  renderMarkdownExport,
+} from './projections.js';
 export {
   actorSchema,
+  agentAliasSchema,
   agentIdSchema,
+  agentLookupSchema,
+  bindRuntimeSchema,
   changesInputSchema,
   createAgentSchema,
   createNoteSchema,
+  createTaskSchema,
   createTodoSchema,
   eventSchema,
   evidenceSchema,
@@ -55,6 +64,7 @@ export {
   profileSchema,
   reviseNoteSchema,
   sendMemoSchema,
+  updateTaskSchema,
   updateTodoSchema,
   updateAgentSchema,
 } from './schemas.js';

package/src/mcp/index.ts

@@ -9,12 +9,14 @@ import {
   agentIdSchema,
   changesInputSchema,
   createNoteSchema,
+  createTaskSchema,
   createTodoSchema,
   giveKudosMcpSchema,
   itemListInputSchema,
   listInputSchema,
   reviseNoteSchema,
   sendMemoSchema,
+  updateTaskSchema,
   updateTodoSchema,
 } from '../schemas.js';
 import { packageVersion } from '../version.js';
@@ -93,7 +95,7 @@ export async function createSynomemMcpServer(
     { name: 'synomem', version: packageVersion() },
     {
       instructions:
-        'Use Synomem for durable kudos, memos, notes, and todos. Store only necessary, factual content; never secrets or raw sensitive tool output. The server binds every write to its configured actor.',
+        'Use Synomem for durable kudos, memos, notes, and tasks. Store only necessary, factual content; never secrets or raw sensitive tool output. The server binds every write to its configured actor.',
     },
   );
 
@@ -324,6 +326,129 @@ export async function createSynomemMcpServer(
     },
   );
 
+  server.registerTool(
+    'synomem_post_create',
+    {
+      title: 'Publish a post',
+      description:
+        'Publish something the whole workspace can read. Use for an announcement, a decision, or context several agents need. A post has no recipient — if one named actor must act, send a memo or assign a task instead.',
+      inputSchema: z.object({
+        title: z.string().trim().min(1).max(200),
+        body: z.string().trim().min(1).max(32_000),
+        tags: z.array(z.string()).max(20).optional(),
+        replyTo: z.string().length(26).optional(),
+        idempotencyKey: z.string().max(200).optional(),
+      }),
+      outputSchema,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async (input) => {
+      try {
+        const result = await client.posts.create(input);
+        return success(actor, `Published post ${result.record.event.id}.`, {
+          post: result.record,
+        });
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
+  server.registerTool(
+    'synomem_post_acknowledge',
+    {
+      title: 'Acknowledge a post',
+      description:
+        'Record that YOU have seen a post. This speaks only for the configured actor and is never implied by reading one: acknowledge when you have actually taken it in, not to clear a list. An optional note tells the author something useful, such as work already done.',
+      inputSchema: z.object({
+        postId: z.string().length(26),
+        note: z.string().trim().min(1).max(2000).optional(),
+        idempotencyKey: z.string().max(200).optional(),
+      }),
+      outputSchema,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    },
+    async (input) => {
+      try {
+        const record = await client.posts.acknowledge(input);
+        return success(actor, `Acknowledged post ${input.postId}.`, { post: record });
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
+  server.registerTool(
+    'synomem_post_roster',
+    {
+      title: 'See who has acknowledged a post',
+      description:
+        'Who has acknowledged a post and who has not. An outstanding entry means no acknowledgement was recorded — never that somebody has not read it. Agents created after the post are counted separately, because they were not there when it was written. This is read-only and does not acknowledge anything.',
+      inputSchema: z.object({ postId: z.string().length(26) }),
+      outputSchema,
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    },
+    async ({ postId }) => {
+      try {
+        const roster = await client.posts.roster(postId);
+        return success(
+          actor,
+          `${roster.acknowledged.length} acknowledged, ${roster.outstanding.length} with no acknowledgement recorded.`,
+          roster,
+        );
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
+  server.registerTool(
+    'synomem_agent_resolve',
+    {
+      title: 'Resolve an agent name',
+      description:
+        'Resolve a name or alias to exactly one agent. Matching ignores case. When several agents answer to the name, no match is returned and the candidates are listed instead — ask which one is meant rather than choosing.',
+      inputSchema: z.object({
+        query: z.string().min(1).describe('An agent ID or alias, in any casing.'),
+      }),
+      outputSchema,
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    },
+    async ({ query }) => {
+      try {
+        const resolution = await client.agents.resolve(query);
+        const message = resolution.match
+          ? `"${resolution.query}" resolves to ${resolution.match.id}.`
+          : resolution.candidates.length
+            ? `"${resolution.query}" is ambiguous across ${resolution.candidates.length} agents. Ask which one is meant.`
+            : `No agent answers to "${resolution.query}".`;
+        return success(actor, message, resolution);
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
+  server.registerTool(
+    'synomem_agent_directory',
+    {
+      title: 'Browse the agent directory',
+      description:
+        'List known agents with their aliases and runtime bindings. Runtime bindings describe where an agent was registered to run and when Synomem last observed it act; they never mean the agent is reachable now. This is read-only.',
+      inputSchema: z.object({}),
+      outputSchema,
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    },
+    async () => {
+      try {
+        const entries = await client.agents.directory();
+        return success(actor, `Found ${entries.length} agent identity or identities.`, { entries });
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
   server.registerTool(
     'synomem_rebuild',
     {
@@ -377,7 +502,7 @@ export async function createSynomemMcpServer(
     {
       title: 'List Synomem items',
       description:
-        'Discover a bounded page of compact kudos, memo, note, and todo summaries. Full bodies, reasons, evidence, descriptions, source, and metadata are omitted; use synomem_get for one selected item.',
+        'Discover a bounded page of compact kudos, memo, note, and task summaries. Full bodies, reasons, evidence, descriptions, source, and metadata are omitted; use synomem_get for one selected item.',
       inputSchema: itemListInputSchema,
       outputSchema,
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
@@ -401,7 +526,7 @@ export async function createSynomemMcpServer(
     {
       title: 'Get one Synomem item',
       description:
-        'Read the full authorized record for one explicitly selected kudos, memo, note, or todo ID.',
+        'Read the full authorized record for one explicitly selected kudos, memo, note, or task ID.',
       inputSchema: z.object({ itemId: z.string().length(26) }),
       outputSchema,
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
@@ -445,7 +570,7 @@ export async function createSynomemMcpServer(
     {
       title: 'Review an agent inbox',
       description:
-        'Return compact pending kudos, unread memos, and open todos for the configured agent. An agent may inspect only its own private items.',
+        'Return compact pending kudos, unread memos, and open tasks for the configured agent. An agent may inspect only its own private items.',
       inputSchema: z.object({
         limit: z.number().int().min(1).max(50).default(10),
         cursor: z.string().max(500).optional(),
@@ -585,12 +710,58 @@ export async function createSynomemMcpServer(
     },
   );
 
+  server.registerTool(
+    'synomem_task_create',
+    {
+      title: 'Create a task',
+      description:
+        'Create a concrete actionable task assigned to an agent, optionally with a date-only or timezone-aware deadline. Do not use as a substitute for a memo when no action is required.',
+      inputSchema: createTaskSchema,
+      outputSchema,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async (input) => {
+      try {
+        const result = await client.tasks.create(input);
+        return success(
+          actor,
+          `${result.deduplicated ? 'Returned existing' : 'Created'} task “${result.record.current.title}” for ${result.record.event.assigneeDisplayName} (ID ${result.record.event.id}).`,
+          result,
+        );
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+  server.registerTool(
+    'synomem_task_update',
+    {
+      title: 'Update a task',
+      description:
+        'Append an update to an open task using the version last read. Stale versions fail rather than overwriting concurrent work.',
+      inputSchema: updateTaskSchema,
+      outputSchema,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    },
+    async (input) => {
+      try {
+        const record = await client.tasks.update(input);
+        return success(
+          actor,
+          `Updated task ${record.event.id} to version ${record.current.version}.`,
+          { record },
+        );
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
   server.registerTool(
     'synomem_todo_create',
     {
-      title: 'Create a todo',
+      title: 'Create a private todo',
       description:
-        'Create a concrete actionable todo assigned to an agent, optionally with a date-only or timezone-aware deadline. Do not use as a substitute for a memo when no action is required.',
+        'Create a private reminder for yourself. A todo has no assignee and nobody else can read it — use synomem_task_create when the work belongs to another agent.',
       inputSchema: createTodoSchema,
       outputSchema,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
@@ -600,7 +771,7 @@ export async function createSynomemMcpServer(
         const result = await client.todos.create(input);
         return success(
           actor,
-          `${result.deduplicated ? 'Returned existing' : 'Created'} todo “${result.record.current.title}” for ${result.record.event.assigneeDisplayName} (ID ${result.record.event.id}).`,
+          `${result.deduplicated ? 'Returned existing' : 'Created'} private todo “${result.record.current.title}” (ID ${result.record.event.id}).`,
           result,
         );
       } catch (error) {
@@ -611,9 +782,9 @@ export async function createSynomemMcpServer(
   server.registerTool(
     'synomem_todo_update',
     {
-      title: 'Update a todo',
+      title: 'Update a private todo',
       description:
-        'Append an update to an open todo using the version last read. Stale versions fail rather than overwriting concurrent work.',
+        'Append an update to one of your own todos using the version last read. Stale versions fail rather than overwriting concurrent work.',
       inputSchema: updateTodoSchema,
       outputSchema,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
@@ -624,15 +795,17 @@ export async function createSynomemMcpServer(
         return success(
           actor,
           `Updated todo ${record.event.id} to version ${record.current.version}.`,
-          { record },
+          {
+            record,
+          },
         );
       } catch (error) {
         return failure(actor, error);
       }
     },
   );
-  for (const operation of ['accept', 'reject', 'complete', 'reopen', 'cancel'] as const) {
-    const inputSchema = z.object({
+  for (const operation of ['complete', 'reopen', 'cancel', 'archive'] as const) {
+    const todoInputSchema = z.object({
       todoId: z.string().length(26),
       note: z.string().trim().min(1).max(2000).optional(),
       reason: z.string().trim().min(1).max(2000).optional(),
@@ -641,9 +814,9 @@ export async function createSynomemMcpServer(
     server.registerTool(
       `synomem_todo_${operation}`,
       {
-        title: `${operation[0]!.toUpperCase()}${operation.slice(1)} a todo`,
-        description: `${operation[0]!.toUpperCase()}${operation.slice(1)} an authorized todo by appending a lifecycle event; history is never deleted.`,
-        inputSchema,
+        title: `${operation[0]!.toUpperCase()}${operation.slice(1)} a private todo`,
+        description: `${operation[0]!.toUpperCase()}${operation.slice(1)} one of your own todos by appending a lifecycle event; history is never deleted.`,
+        inputSchema: todoInputSchema,
         outputSchema,
         annotations: {
           readOnlyHint: false,
@@ -654,34 +827,96 @@ export async function createSynomemMcpServer(
       async (input) => {
         try {
           const record =
-            operation === 'accept'
-              ? await client.todos.accept({
+            operation === 'complete'
+              ? await client.todos.complete({
                   todoId: input.todoId,
+                  ...(input.note ? { note: input.note } : {}),
                   ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
                 })
-              : operation === 'reject'
-                ? await client.todos.reject({
+              : operation === 'cancel'
+                ? await client.todos.cancel({
                     todoId: input.todoId,
                     ...(input.reason ? { reason: input.reason } : {}),
                     ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
                   })
-                : operation === 'complete'
-                  ? await client.todos.complete({
+                : operation === 'archive'
+                  ? await client.todos.archive({
+                      todoId: input.todoId,
+                      ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+                    })
+                  : await client.todos.reopen({
                       todoId: input.todoId,
+                      ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+                    });
+          return success(actor, `Todo ${record.event.id} is now ${record.status}.`, { record });
+        } catch (error) {
+          return failure(actor, error);
+        }
+      },
+    );
+  }
+
+  for (const operation of ['accept', 'reject', 'complete', 'reopen', 'cancel'] as const) {
+    const inputSchema = z.object({
+      taskId: z.string().length(26),
+      note: z.string().trim().min(1).max(2000).optional(),
+      reason: z.string().trim().min(1).max(2000).optional(),
+      // Required on reject, optional on accept. Declaring it required in the
+      // tool schema for reject means a model is told before it calls, rather
+      // than discovering it from an error.
+      ...(operation === 'reject'
+        ? { response: z.string().trim().min(1).max(2000) }
+        : operation === 'accept'
+          ? { response: z.string().trim().min(1).max(2000).optional() }
+          : {}),
+      idempotencyKey: z.string().max(200).optional(),
+    });
+    server.registerTool(
+      `synomem_task_${operation}`,
+      {
+        title: `${operation[0]!.toUpperCase()}${operation.slice(1)} a task`,
+        description: `${operation[0]!.toUpperCase()}${operation.slice(1)} an authorized task by appending a lifecycle event; history is never deleted.`,
+        inputSchema,
+        outputSchema,
+        annotations: {
+          readOnlyHint: false,
+          destructiveHint: operation === 'cancel',
+          idempotentHint: true,
+        },
+      },
+      async (input) => {
+        try {
+          const record =
+            operation === 'accept'
+              ? await client.tasks.accept({
+                  taskId: input.taskId,
+                  ...('response' in input && input.response ? { response: input.response } : {}),
+                  ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+                })
+              : operation === 'reject'
+                ? await client.tasks.reject({
+                    taskId: input.taskId,
+                    response:
+                      ('response' in input ? input.response : undefined) ?? input.reason ?? '',
+                    ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+                  })
+                : operation === 'complete'
+                  ? await client.tasks.complete({
+                      taskId: input.taskId,
                       ...(input.note ? { note: input.note } : {}),
                       ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
                     })
                   : operation === 'cancel'
-                    ? await client.todos.cancel({
-                        todoId: input.todoId,
+                    ? await client.tasks.cancel({
+                        taskId: input.taskId,
                         ...(input.reason ? { reason: input.reason } : {}),
                         ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
                       })
-                    : await client.todos.reopen({
-                        todoId: input.todoId,
+                    : await client.tasks.reopen({
+                        taskId: input.taskId,
                         ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
                       });
-          return success(actor, `Todo ${record.event.id} is ${record.status}.`, { record });
+          return success(actor, `Task ${record.event.id} is ${record.status}.`, { record });
         } catch (error) {
           return failure(actor, error);
         }
@@ -758,7 +993,7 @@ export async function createSynomemMcpServer(
     new ResourceTemplate('synomem://agents/{agentId}/inbox', { list: undefined }),
     {
       title: 'Agent inbox',
-      description: 'Ten recent visible pending kudos, memos, and todos for one agent',
+      description: 'Ten recent visible pending kudos, memos, and tasks for one agent',
       mimeType: 'application/json',
     },
     async (uri, { agentId }) => {
@@ -932,9 +1167,9 @@ export async function createSynomemMcpServer(
   );
 
   server.registerPrompt(
-    'synomem_create_actionable_todo',
+    'synomem_create_actionable_task',
     {
-      title: 'Create an actionable todo',
+      title: 'Create an actionable task',
       description:
         'Turn requested work into a concrete assigned action without inventing deadlines.',
       argsSchema: { assignee: agentIdSchema, action: z.string() },
@@ -945,7 +1180,7 @@ export async function createSynomemMcpServer(
           role: 'user',
           content: {
             type: 'text',
-            text: `Prepare a concrete todo assigned to ${assignee}: ${action}. Preserve a date-only deadline as a date, require timezone data for a timed deadline, and do not invent missing timing.`,
+            text: `Prepare a concrete task assigned to ${assignee}: ${action}. Preserve a date-only deadline as a date, require timezone data for a timed deadline, and do not invent missing timing.`,
           },
         },
       ],

package/src/mcp-server.ts

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
+import { createConfiguredService } from './backend.js';
+import { SynomemError } from './errors.js';
 import { actorSchema } from './schemas.js';
 import { startMcpServer } from './mcp/index.js';
+import type { ActorIdentity } from './types.js';
 import { packageVersion } from './version.js';
 
 const version = packageVersion();
@@ -9,6 +12,7 @@ const version = packageVersion();
 const { values } = parseArgs({
   options: {
     home: { type: 'string' },
+    'agent-id': { type: 'string' },
     'actor-id': { type: 'string' },
     'actor-kind': { type: 'string' },
     'actor-name': { type: 'string' },
@@ -17,6 +21,43 @@ const { values } = parseArgs({
   },
 });
 
+/**
+ * Loads an agent's identity from canonical state rather than from arguments.
+ *
+ * A display name passed on the command line is a claim the runtime makes about
+ * itself, and it is written into every event the session appends. Reading the
+ * profile instead means a misconfigured runtime cannot sign another agent's
+ * name to work, and renaming an agent takes effect without re-registering it
+ * with every harness.
+ */
+async function resolveAgentActor(agentId: string, home?: string): Promise<ActorIdentity> {
+  const lookup = createConfiguredService({
+    actor: { kind: 'system', id: 'synomem-mcp' },
+    ...(home ? { home } : {}),
+  });
+  await lookup.init();
+  try {
+    const resolution = await lookup.agents.resolve(agentId);
+    if (!resolution.match) {
+      throw new SynomemError(
+        'AGENT_NOT_FOUND',
+        resolution.candidates.length
+          ? `"${agentId}" matches ${resolution.candidates.length} agents: ${resolution.candidates
+              .map((candidate) => candidate.id)
+              .join(', ')}. Register the MCP server with a canonical agent ID.`
+          : `Unknown agent: ${agentId}. Create it with \`synomem agent create\` first.`,
+      );
+    }
+    return {
+      kind: 'agent',
+      id: resolution.match.id,
+      ...(resolution.match.displayName ? { displayName: resolution.match.displayName } : {}),
+    };
+  } finally {
+    await lookup.close();
+  }
+}
+
 if (values.help) {
   process.stdout.write(`synomem-mcp ${version}
 
@@ -24,20 +65,29 @@ Actor-bound Synomem MCP server (stdio transport)
 
 Options:
   --home <path>          Storage root
-  --actor-id <id>        Bound actor ID (or SYNOMEM_ACTOR_ID)
-  --actor-kind <kind>    human, agent, or system (or SYNOMEM_ACTOR_KIND)
-  --actor-name <name>    Optional display name (or SYNOMEM_ACTOR_NAME)
+  --agent-id <id>        Bound agent, whose identity is read from Synomem
+                         (or SYNOMEM_AGENT_ID)
+  --actor-id <id>        Bound non-agent actor ID (or SYNOMEM_ACTOR_ID)
+  --actor-kind <kind>    human or system (or SYNOMEM_ACTOR_KIND)
+  --actor-name <name>    Display name for a non-agent actor
+                         (or SYNOMEM_ACTOR_NAME)
   -h, --help             Show help
   -v, --version          Show version
+
+Prefer --agent-id for an agent runtime: the display name and kind then come
+from the agent's profile instead of from whatever the harness was told to pass.
 `);
 } else if (values.version) {
   process.stdout.write(`${version}\n`);
 } else {
-  const actor = actorSchema.parse({
-    id: values['actor-id'] ?? process.env.SYNOMEM_ACTOR_ID,
-    kind: values['actor-kind'] ?? process.env.SYNOMEM_ACTOR_KIND,
-    displayName: values['actor-name'] ?? process.env.SYNOMEM_ACTOR_NAME,
-  });
+  const agentId = values['agent-id'] ?? process.env.SYNOMEM_AGENT_ID;
+  const actor = agentId
+    ? await resolveAgentActor(agentId, values.home)
+    : actorSchema.parse({
+        id: values['actor-id'] ?? process.env.SYNOMEM_ACTOR_ID,
+        kind: values['actor-kind'] ?? process.env.SYNOMEM_ACTOR_KIND,
+        displayName: values['actor-name'] ?? process.env.SYNOMEM_ACTOR_NAME,
+      });
 
   await startMcpServer({
     actor,

package/src/ports/repository.ts

@@ -1,8 +1,12 @@
 import type {
   ActorIdentity,
   AgentProfile,
+  AgentRuntimeBinding,
   ChangePage,
   ItemListInput,
+  JsonValue,
+  PostAcknowledgment,
+  PostRoster,
   ItemSummary,
   KudosListInput,
   KudosSummary,
@@ -41,6 +45,23 @@ export interface SynomemRepository {
   updateAgent(profile: AgentProfile, updatedAt: string): Awaitable<void>;
   getAgent(idOrAlias: string): Awaitable<AgentProfile | undefined>;
   listAgents(): Awaitable<AgentProfile[]>;
+  /** Resolves a name case-insensitively, reporting ambiguity instead of guessing. */
+  resolveAgent(query: string): Awaitable<{ match?: AgentProfile; candidates: AgentProfile[] }>;
+  listPostAcknowledgments(postId: string): Awaitable<PostAcknowledgment[]>;
+  /** Who has acknowledged a post and who has not; see PostRoster. */
+  postRoster(postId: string): Awaitable<PostRoster | undefined>;
+  listRuntimeBindings(agentId: string): Awaitable<AgentRuntimeBinding[]>;
+  bindRuntime(binding: {
+    id: string;
+    agentId: string;
+    installationId?: string;
+    runtime: string;
+    profile?: string;
+    capabilities?: Record<string, JsonValue>;
+    boundAt: string;
+  }): Awaitable<void>;
+  unbindRuntime(bindingId: string): Awaitable<boolean>;
+  touchRuntimeBinding(agentId: string, runtime: string, at: string): Awaitable<void>;
 
   listKudosSummaries(
     input: Required<Pick<KudosListInput, 'limit' | 'offset'>> & KudosListInput,