@jungjaehoon/mama-os 0.58.0 → 0.59.0

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.58.1] - 2026-09-29
+
+### Changed
+
+- Each owner action is listed with its arguments; `help` returns types, descriptions and examples
+  as text; the tool-use example shows a targeted, filtered read. See the root CHANGELOG.
+
 ## [0.58.0] - 2026-09-29
 
 The owner agent runs in the reference operator's structure: a short session start, lessons that

package/README.md

@@ -4,7 +4,7 @@ One owner agent on Claude or Codex watches connected work, keeps task revisions
 answers on Telegram, publishes reports and a board, and recalls corrections.
 [mama-core](../mama-core/README.md) supplies the shared engine.
 
-Current manifest: **0.58.0**. This README describes the unreleased `rebuild/owner-flow` source.
+Current manifest: **0.59.0**. This README describes the unreleased `rebuild/owner-flow` source.
 Use [owner setup](../../docs/start/owner-setup.md) with Node.js 22.13+ and pnpm.
 
 ## Start and operate

package/dist/api/code-act-actions.d.ts

@@ -0,0 +1,28 @@
+import type { ActionContract, ActionDispatcher, ActionRegistration } from '@jungjaehoon/mama-core';
+export interface CodeActHost {
+    /** The action names the code may call, e.g. `work.list`. */
+    functions: readonly {
+        name: string;
+    }[];
+    call(name: string, input: unknown): Promise<unknown>;
+}
+export interface CodeActResult {
+    success: boolean;
+    value?: unknown;
+    error?: {
+        name: string;
+        message: string;
+    };
+    logs: string[];
+    hostCallCount: number;
+    durationMs: number;
+}
+/** Run the code in a fresh worker process; host calls are answered by `host.call`. */
+export declare function runCodeAct(code: string, host: CodeActHost, timeoutMs?: number): Promise<CodeActResult>;
+export declare const CODE_ACT_CONTRACT: ActionContract;
+/**
+ * The code_act action over a dispatcher built after it: the functions are the actions the
+ * caller is granted, and each call is dispatched with the caller's own context.
+ */
+export declare function codeActRegistration(dispatcher: () => ActionDispatcher): ActionRegistration;
+//# sourceMappingURL=code-act-actions.d.ts.map

package/dist/api/code-act-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-act-actions.d.ts","sourceRoot":"","sources":["../../src/api/code-act-actions.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAEV,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,wBAAwB,CAAC;AAgEhC,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,SAAS,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACvC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAID,sFAAsF;AACtF,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,WAAW,EACjB,SAAS,SAAqB,GAC7B,OAAO,CAAC,aAAa,CAAC,CA+FxB;AAED,eAAO,MAAM,iBAAiB,EAAE,cAiB/B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,gBAAgB,GAAG,kBAAkB,CAoC1F"}

package/dist/api/code-act-actions.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODE_ACT_CONTRACT = void 0;
+exports.runCodeAct = runCodeAct;
+exports.codeActRegistration = codeActRegistration;
+/**
+ * code_act: the agent runs one piece of JavaScript that calls several actions, instead of
+ * one model round trip per action.
+ *
+ * Mechanism ported from Kagemusha's code-act sandbox and worker. The code runs in its own
+ * Node process; every action it calls is relayed over IPC to this process and dispatched
+ * with the calling turn's own context, so the grant, session and traces are the caller's.
+ * The worker runs under Node's permission model: `vm` gives the code a clean namespace but
+ * is not a boundary, and an escaped script must reach no files, processes or network.
+ */
+const node_child_process_1 = require("node:child_process");
+const WORKER_SOURCE = `
+const vm = require('node:vm');
+const pending = new Map();
+let nextId = 0;
+function callTool(name, params) {
+  const id = String(++nextId);
+  return new Promise((resolve, reject) => {
+    pending.set(id, { resolve, reject });
+    process.send({ type: 'callTool', id, name, params });
+  });
+}
+function assignNested(root, path, fn) {
+  let cursor = root;
+  for (let i = 0; i < path.length - 1; i++) {
+    if (!cursor[path[i]] || typeof cursor[path[i]] !== 'object') cursor[path[i]] = {};
+    cursor = cursor[path[i]];
+  }
+  cursor[path[path.length - 1]] = fn;
+}
+process.on('disconnect', () => process.exit(1));
+process.on('message', async (msg) => {
+  if (msg.type === 'toolResult') {
+    const call = pending.get(msg.id);
+    if (!call) return;
+    pending.delete(msg.id);
+    if (msg.error !== undefined) call.reject(new Error(msg.error));
+    else call.resolve(msg.result);
+    return;
+  }
+  if (msg.type !== 'execute') return;
+  const logs = [];
+  const sandbox = {
+    console: { log: (...args) => logs.push(args.map((a) => (typeof a === 'string' ? a : JSON.stringify(a))).join(' ')) },
+    callTool,
+  };
+  for (const name of msg.functionNames) {
+    const proxy = (params) => callTool(name, params);
+    if (name.includes('.')) assignNested(sandbox, name.split('.'), proxy);
+    else sandbox[name] = proxy;
+  }
+  sandbox.globalThis = sandbox;
+  try {
+    const trimmed = msg.code.trim();
+    // A single line with no statement keyword is returned; its closing semicolon is dropped.
+    const expression = trimmed.replace(/;$/, '');
+    const needsReturn =
+      !expression.startsWith('return ') && !expression.startsWith('return\\n') && !expression.includes('\\n') &&
+      !/^(if|for|while|var|let|const|switch|try|throw|class|function)\\b/.test(expression);
+    const body = needsReturn ? 'return ' + expression : msg.code;
+    const script = new vm.Script('(async () => { ' + body + '\\n})()', { filename: 'code_act.js' });
+    const value = await script.runInContext(vm.createContext(sandbox), { timeout: msg.timeoutMs });
+    process.send({ type: 'result', success: true, value, logs }, () => process.exit(0));
+  } catch (error) {
+    process.send(
+      { type: 'result', success: false, logs, error: { name: error && error.name ? error.name : 'Error', message: error && error.message ? error.message : String(error) } },
+      () => process.exit(0)
+    );
+  }
+});
+process.send({ type: 'ready' });
+`;
+const DEFAULT_TIMEOUT_MS = 300_000;
+/** Run the code in a fresh worker process; host calls are answered by `host.call`. */
+function runCodeAct(code, host, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const startedAt = Date.now();
+    let hostCallCount = 0;
+    return new Promise((resolve) => {
+        // An empty environment: --permission does not guard process.env, and the daemon's holds
+        // MAMA's own credentials (auth.env), which an escaped script must not read.
+        const child = (0, node_child_process_1.spawn)(process.execPath, ['--permission', '-e', WORKER_SOURCE], {
+            stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+            env: {},
+        });
+        let stderr = '';
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            child.kill('SIGKILL');
+            resolve({ ...result, hostCallCount, durationMs: Date.now() - startedAt });
+        };
+        const timer = setTimeout(() => settle({
+            success: false,
+            error: { name: 'TimeoutError', message: `code_act timed out after ${timeoutMs}ms` },
+            logs: [],
+        }), timeoutMs);
+        child.stderr.on('data', (chunk) => {
+            // Keep the tail only: an escaped script could write to stderr for the whole timeout.
+            stderr = (stderr + chunk.toString('utf8')).slice(-2000);
+        });
+        child.on('message', async (msg) => {
+            if (msg.type === 'ready') {
+                child.send({
+                    type: 'execute',
+                    code,
+                    functionNames: host.functions.map((fn) => fn.name),
+                    timeoutMs,
+                });
+                return;
+            }
+            if (msg.type === 'callTool') {
+                // A call that arrives after a timeout must not start an action nobody will see.
+                if (settled)
+                    return;
+                hostCallCount += 1;
+                try {
+                    const result = await host.call(msg.name, msg.params);
+                    if (child.connected)
+                        child.send({ type: 'toolResult', id: msg.id, result });
+                }
+                catch (error) {
+                    if (child.connected)
+                        child.send({
+                            type: 'toolResult',
+                            id: msg.id,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                }
+                return;
+            }
+            if (msg.type === 'result') {
+                settle(msg.success
+                    ? { success: true, value: msg.value, logs: msg.logs ?? [] }
+                    : { success: false, error: msg.error, logs: msg.logs ?? [] });
+            }
+        });
+        child.on('error', (error) => settle({ success: false, error: { name: 'WorkerError', message: error.message }, logs: [] }));
+        child.on('exit', (exitCode, signal) => {
+            // A clean exit follows the result message; anything else lost the result.
+            if (exitCode === 0 && signal === null)
+                return;
+            settle({
+                success: false,
+                error: {
+                    name: 'WorkerError',
+                    message: `code_act worker exited (code=${exitCode}, signal=${signal})${stderr ? `: ${stderr.trim().slice(0, 500)}` : ''}`,
+                },
+                logs: [],
+            });
+        });
+    });
+}
+exports.CODE_ACT_CONTRACT = {
+    name: 'code_act',
+    summary: 'Run JavaScript that calls MAMA actions and returns only what the turn needs. Every action is an async function by its name, e.g. `return (await work.list({ view: "items", text: "asset" })).tasks.map((task) => [task.title, task.status])`; a failed action throws with its error; independent calls go together with `Promise.all`; `help({ actions: ["work.revise"] })` returns an action\'s argument types and examples; a name with a colon is called as `memory["read:provenance"]({...})`. The code runs in a separate process with no file or process access and an empty environment; its return value, console.log lines and any error come back.',
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['code'],
+        properties: {
+            code: {
+                type: 'string',
+                minLength: 1,
+                description: 'The body of an async function, e.g. const [recent, days] = await Promise.all([source.recent({ since: "24h ago" }), schedule.upcoming({ days: 14 })]); return { channels: recent.channels.length, events: days.events.length };',
+            },
+        },
+    },
+};
+/**
+ * The code_act action over a dispatcher built after it: the functions are the actions the
+ * caller is granted, and each call is dispatched with the caller's own context.
+ */
+function codeActRegistration(dispatcher) {
+    return {
+        contract: exports.CODE_ACT_CONTRACT,
+        exec: async (input, context) => {
+            const dispatch = dispatcher();
+            const granted = new Set(context.access.actions ?? []);
+            const functions = dispatch.contracts
+                .filter((contract) => contract.name !== exports.CODE_ACT_CONTRACT.name && granted.has(contract.name))
+                .map((contract) => ({ name: contract.name }));
+            // Inner writes take their command ids from this one; without it two calls would collide.
+            const operationId = context.operationId;
+            if (!operationId)
+                throw new Error('code_act requires an operation id');
+            const callable = new Set(functions.map((fn) => fn.name));
+            let calls = 0;
+            return runCodeAct(input.code, {
+                functions,
+                call: async (name, params) => {
+                    // callTool() takes any name; code_act itself would start a worker inside a worker.
+                    if (!callable.has(name))
+                        throw new Error(`action_not_granted: ${name}`);
+                    calls += 1;
+                    const result = await dispatch({
+                        action: name,
+                        input: params ?? {},
+                        operationId: `${operationId}#${calls}`,
+                    }, context);
+                    if (result.status === 'completed')
+                        return result.data;
+                    throw new Error(`${result.error.code}: ${result.error.message}`);
+                },
+            });
+        },
+    };
+}
+//# sourceMappingURL=code-act-actions.js.map

package/dist/api/code-act-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-act-actions.js","sourceRoot":"","sources":["../../src/api/code-act-actions.ts"],"names":[],"mappings":"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"}

package/dist/api/help-actions.d.ts

@@ -1,12 +1,20 @@
 import type { ActionContract, ActionRegistration } from '@jungjaehoon/mama-core';
 /**
- * The first sentence of an action's summary: what every turn shows for it. The full contract is
- * one `help` call away, as Kagemusha keeps a one-line catalog and serves detail through `help()`.
+ * The argument list the agent calls with, as Kagemusha's code_act description lists
+ * `task_update({id, status, priority, deadline})`: top-level names, `?` for optional ones, the
+ * allowed values of a plain enum and the bound of a number, list or text.
  */
-export declare function actionCatalogLine(summary: string): string;
+export declare function actionSignature(inputSchema: unknown): string;
+/**
+ * What every turn shows for an action: its name and first sentence, an index entry. The
+ * arguments come from help({actions: [name]}) when the agent is about to call it.
+ */
+export declare function actionCatalogLine(contract: Pick<ActionContract, 'name' | 'summary'>): string;
 export interface HelpActionPorts {
     /** The granted contracts, read when `help` runs so it sees the finished catalog. */
     contracts(): readonly ActionContract[];
+    /** The procedures a turn reads when it needs one, by topic name. */
+    topics?(): Readonly<Record<string, string>>;
 }
 export declare function helpActionRegistrations(ports: HelpActionPorts): ActionRegistration[];
 //# sourceMappingURL=help-actions.d.ts.map

package/dist/api/help-actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help-actions.d.ts","sourceRoot":"","sources":["../../src/api/help-actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKzD;AAQD,MAAM,WAAW,eAAe;IAC9B,oFAAoF;IACpF,SAAS,IAAI,SAAS,cAAc,EAAE,CAAC;CACxC;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,kBAAkB,EAAE,CAiDpF"}
+{"version":3,"file":"help-actions.d.ts","sourceRoot":"","sources":["../../src/api/help-actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AA8DjF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,OAAO,GAAG,MAAM,CAU5D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,CAE5F;AA2ED,MAAM,WAAW,eAAe;IAC9B,oFAAoF;IACpF,SAAS,IAAI,SAAS,cAAc,EAAE,CAAC;IACvC,oEAAoE;IACpE,MAAM,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7C;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,kBAAkB,EAAE,CAiEpF"}

package/dist/api/help-actions.js

@@ -1,17 +1,149 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.actionSignature = actionSignature;
 exports.actionCatalogLine = actionCatalogLine;
 exports.helpActionRegistrations = helpActionRegistrations;
-/**
- * The first sentence of an action's summary: what every turn shows for it. The full contract is
- * one `help` call away, as Kagemusha keeps a one-line catalog and serves detail through `help()`.
- */
-function actionCatalogLine(summary) {
+function asSchema(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function firstSentence(summary) {
     const flat = summary.replace(/\s+/g, ' ').trim();
     const end = flat.search(/[.!?](\s|$)/);
     const first = end === -1 ? flat : flat.slice(0, end + 1);
     return first.length <= 160 ? first : `${first.slice(0, 157)}...`;
 }
+/** Top-level arguments in schema order, required ones first; `?` marks an optional one. */
+function orderedProperties(schema) {
+    const properties = asSchema(schema.properties);
+    if (!properties)
+        return [];
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const entries = Object.entries(properties);
+    return [
+        ...entries.filter(([name]) => required.has(name)).map(([name, value]) => [name, value, true]),
+        ...entries.filter(([name]) => !required.has(name)).map(([name, value]) => [name, value, false]),
+    ];
+}
+function enumText(schema) {
+    if ('const' in schema)
+        return JSON.stringify(schema.const);
+    return Array.isArray(schema.enum)
+        ? schema.enum.map((value) => JSON.stringify(value)).join('|')
+        : null;
+}
+/**
+ * The argument sets a top-level `oneOf`/`anyOf` requires, e.g. `observationRef | observationRefs`
+ * for `source.read`, when each alternative only names required arguments.
+ */
+function requiredChoice(schema) {
+    const alternatives = Array.isArray(schema.oneOf) ? schema.oneOf : schema.anyOf;
+    if (!Array.isArray(alternatives))
+        return null;
+    const sets = alternatives.map((alternative) => {
+        const required = asSchema(alternative)?.required;
+        return Array.isArray(required) && required.length > 0 ? required.join(' + ') : null;
+    });
+    return sets.every((set) => set !== null) ? sets.join(' | ') : null;
+}
+/**
+ * The bound a caller cannot guess from the name, e.g. `≤50` for a limit, `≤4 items` for a list or
+ * `≤1024 chars` for a caption:
+ * on the first live day the agent sent `limit: 100` to `work.list`, whose maximum is 50.
+ */
+function boundText(schema) {
+    if (typeof schema.maximum === 'number')
+        return `≤${schema.maximum}`;
+    if (typeof schema.maxItems === 'number')
+        return `≤${schema.maxItems} items`;
+    if (typeof schema.maxLength === 'number')
+        return `≤${schema.maxLength} chars`;
+    return null;
+}
+/**
+ * The argument list the agent calls with, as Kagemusha's code_act description lists
+ * `task_update({id, status, priority, deadline})`: top-level names, `?` for optional ones, the
+ * allowed values of a plain enum and the bound of a number, list or text.
+ */
+function actionSignature(inputSchema) {
+    const schema = asSchema(inputSchema);
+    if (!schema)
+        return '{}';
+    const parts = orderedProperties(schema).map(([name, value, required]) => {
+        const property = asSchema(value);
+        const detail = property ? (enumText(property) ?? boundText(property)) : null;
+        return `${name}${required ? '' : '?'}${detail ? `: ${detail}` : ''}`;
+    });
+    const choice = requiredChoice(schema);
+    return `{${parts.join(', ')}${choice ? `; one of: ${choice}` : ''}}`;
+}
+/**
+ * What every turn shows for an action: its name and first sentence, an index entry. The
+ * arguments come from help({actions: [name]}) when the agent is about to call it.
+ */
+function actionCatalogLine(contract) {
+    return `${contract.name} — ${firstSentence(contract.summary)}`;
+}
+function typeText(value, depth) {
+    const schema = asSchema(value);
+    if (!schema)
+        return 'any';
+    const values = enumText(schema);
+    if (values)
+        return values;
+    const alternatives = Array.isArray(schema.oneOf) ? schema.oneOf : schema.anyOf;
+    if (Array.isArray(alternatives))
+        return alternatives.map((alternative) => typeText(alternative, depth)).join(' | ');
+    if (Array.isArray(schema.type))
+        return schema.type.join(' | ');
+    if (schema.type === 'array') {
+        const item = typeText(schema.items, depth);
+        return `${/[ |]/.test(item) ? `(${item})` : item}[]`;
+    }
+    if (schema.type === 'object' || schema.properties !== undefined) {
+        const properties = orderedProperties(schema);
+        // Two levels show an argument's shape; deeper parts are named `object`, and the argument's
+        // description gives an example of the whole value. Keeping help short is what help is for.
+        if (properties.length === 0 || depth >= 3)
+            return 'object';
+        return `{${properties
+            .map(([name, property, required]) => `${name}${required ? '' : '?'}: ${typeText(property, depth + 1)}`)
+            .join(', ')}}`;
+    }
+    return typeof schema.type === 'string' ? schema.type : 'any';
+}
+const items = (count) => `${count} item${count === 1 ? '' : 's'}`;
+/** The limits the dispatcher enforces on one argument, e.g. ` (at most 4 items)`. */
+function limitsText(value) {
+    const schema = asSchema(value);
+    if (!schema)
+        return '';
+    const limits = [
+        typeof schema.minItems === 'number' ? `at least ${items(schema.minItems)}` : null,
+        typeof schema.maxItems === 'number' ? `at most ${items(schema.maxItems)}` : null,
+        typeof schema.minimum === 'number' ? `min ${schema.minimum}` : null,
+        typeof schema.maximum === 'number' ? `max ${schema.maximum}` : null,
+        typeof schema.maxLength === 'number' ? `at most ${schema.maxLength} chars` : null,
+        typeof schema.pattern === 'string' ? `pattern ${schema.pattern}` : null,
+    ].filter((limit) => limit !== null);
+    return limits.length === 0 ? '' : ` (${limits.join(', ')})`;
+}
+/** One action's contract as plain lines: signature, summary, each argument and the examples. */
+function helpText(contract) {
+    const schema = asSchema(contract.inputSchema) ?? {};
+    const lines = [`${contract.name}(${actionSignature(schema)})`, contract.summary];
+    for (const [name, property, required] of orderedProperties(schema)) {
+        const description = asSchema(property)?.description;
+        lines.push(`- ${name}${required ? ' (required)' : ''}: ${typeText(property, 1)}${limitsText(property)}${typeof description === 'string' ? `. ${description}` : ''}`);
+    }
+    const alternatives = [schema.oneOf, schema.anyOf].find(Array.isArray);
+    if (alternatives)
+        lines.push(`- one of: ${requiredChoice(schema) ?? alternatives.map((alternative) => typeText(alternative, 1)).join(' | ')}`);
+    for (const example of contract.examples ?? [])
+        lines.push(`example (${example.title}): ${JSON.stringify(example.input)}`);
+    return lines.join('\n');
+}
 function invalidInput(message) {
     const error = new Error(message);
     error.name = 'invalid_input';
@@ -22,47 +154,58 @@ function helpActionRegistrations(ports) {
         {
             contract: {
                 name: 'help',
-                summary: "Read actions' full contracts (summary, input schema, examples) before first use; with no names, list every action with its one-line summary.",
+                summary: "Read what you need next, one level at a time: several actions give each one's call signature (arguments, allowed values, bounds) and purpose; one action gives its whole contract with argument descriptions and examples; a topic gives a procedure; with neither, list the topics and actions.",
                 inputSchema: {
                     type: 'object',
                     additionalProperties: false,
                     properties: {
-                        actions: { type: 'array', items: { type: 'string', minLength: 1 } },
+                        actions: { type: 'array', minItems: 1, items: { type: 'string', minLength: 1 } },
+                        topic: { type: 'string', minLength: 1 },
                     },
                 },
                 examples: [
-                    { title: 'Read two contracts', input: { actions: ['work.list', 'report.publish'] } },
+                    { title: 'Read one contract', input: { actions: ['report.publish'] } },
+                    { title: 'Read a procedure', input: { topic: 'full-report' } },
                 ],
             },
             exec: (input) => {
-                const requested = input.actions;
+                const { actions: requested, topic } = input;
                 const contracts = ports.contracts();
-                if (requested === undefined)
-                    return {
-                        actions: contracts.map((contract) => ({
-                            name: contract.name,
-                            summary: actionCatalogLine(contract.summary),
-                        })),
-                    };
+                const topics = ports.topics?.() ?? {};
+                const parts = [];
+                if (topic !== undefined) {
+                    const text = typeof topic === 'string' && Object.hasOwn(topics, topic) ? topics[topic] : undefined;
+                    if (text === undefined)
+                        throw invalidInput(`unknown topic: ${String(topic)}; topics: ${Object.keys(topics).join(', ')}`);
+                    parts.push(text);
+                }
+                if (requested === undefined) {
+                    if (topic !== undefined)
+                        return parts.join('\n\n');
+                    return [
+                        `Topics: ${Object.keys(topics).join(', ')}`,
+                        'Actions:',
+                        ...contracts.map(actionCatalogLine),
+                    ].join('\n');
+                }
                 if (!Array.isArray(requested))
                     throw invalidInput('actions must be a list of action names');
-                // The model sees tools.work_list (Codex) or mcp__mama__work_list (Claude); both name work.list.
-                const key = (name) => name.replace(/^mcp__mama__/, '').replace(/[.:]/g, '_');
+                // Codex sees tools.work_list and Claude calls work.list inside code_act; both name work.list.
+                const key = (name) => name.replace(/[.:]/g, '_');
                 const byName = new Map(contracts.map((contract) => [key(contract.name), contract]));
                 const unknown = requested.filter((name) => !byName.has(key(String(name))));
                 if (unknown.length > 0)
                     throw invalidInput(`unknown actions: ${unknown.join(', ')}`);
-                return {
-                    actions: requested.map((name) => {
-                        const contract = byName.get(key(String(name)));
-                        return {
-                            name: contract.name,
-                            summary: contract.summary,
-                            inputSchema: contract.inputSchema,
-                            ...(contract.examples === undefined ? {} : { examples: contract.examples }),
-                        };
-                    }),
-                };
+                const asked = requested.map((name) => byName.get(key(String(name))));
+                // One level at a time: several actions give their call lines; one gives its contract.
+                if (asked.length === 1)
+                    parts.push(helpText(asked[0]));
+                else
+                    parts.push([
+                        ...asked.map((contract) => `${contract.name}(${actionSignature(contract.inputSchema)}) — ${firstSentence(contract.summary)}`),
+                        'Ask for one action by itself for its argument descriptions and examples.',
+                    ].join('\n'));
+                return parts.join('\n\n');
             },
         },
     ];

package/dist/api/help-actions.js.map

@@ -1 +1 @@
-{"version":3,"file":"help-actions.js","sourceRoot":"","sources":["../../src/api/help-actions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"help-actions.js","sourceRoot":"","sources":["../../src/api/help-actions.ts"],"names":[],"mappings":"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"}

package/dist/api/judge-actions.d.ts

@@ -0,0 +1,25 @@
+import type { ActionRegistration } from '@jungjaehoon/mama-core';
+import type { JevQuestions } from '../replay/jev-client.js';
+/** The Jev call the action makes; the daemon passes the configured client. */
+export interface JudgePorts {
+    ask(request: {
+        state: unknown;
+        questions: JevQuestions;
+        /** The turn's signal: a cancelled turn cancels its Jev request. */
+        signal?: AbortSignal;
+    }): Promise<Record<string, unknown>>;
+}
+/**
+ * The most state one call may carry. Jev's documented rough edge: accuracy falls when the state
+ * holds details unrelated to the question. On 2026-09-29 the agent put the whole open ledger in
+ * each of 24 calls and read their unfiltered results back; one item's record and its few messages
+ * fit well inside this.
+ */
+export declare const JUDGE_STATE_LIMIT = 6000;
+/**
+ * Jev as the agent's own filter: a script reads many candidates, asks narrow typed questions and
+ * returns only the ones that matter, so the rows never enter the model's context. The agent writes
+ * the questions and weighs the answers; the host only carries them to Jev.
+ */
+export declare function judgeActionRegistrations(ports: JudgePorts): ActionRegistration[];
+//# sourceMappingURL=judge-actions.d.ts.map

package/dist/api/judge-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"judge-actions.d.ts","sourceRoot":"","sources":["../../src/api/judge-actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,OAAO,EAAE;QACX,KAAK,EAAE,OAAO,CAAC;QACf,SAAS,EAAE,YAAY,CAAC;QACxB,mEAAmE;QACnE,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtC;AAID;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,OAAQ,CAAC;AAYvC;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,UAAU,GAAG,kBAAkB,EAAE,CA0IhF"}