@jungjaehoon/mama-os 0.59.0 → 0.60.0

package/dist/api/work-actions.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runTaskListView = void 0;
+exports.offsetIsoTime = offsetIsoTime;
 exports.runWorkListView = runWorkListView;
 exports.workListActionRegistrations = workListActionRegistrations;
 exports.assertReplayEventDatetime = assertReplayEventDatetime;
 exports.minimalWorkActionRegistrations = minimalWorkActionRegistrations;
+exports.workLinkRegistration = workLinkRegistration;
 const node_crypto_1 = require("node:crypto");
 const timezone_js_1 = require("../runtime/timezone.js");
 const catalog_1 = require("@jungjaehoon/mama-core/api/catalog");
@@ -14,6 +16,8 @@ const WORK_LIST_DEFAULT_LIMIT = 25;
 const WORK_LIST_MAX_LIMIT = 50;
 const WORK_LIST_MAX_DETAIL_IDS = 4;
 const WORK_LIST_DEFAULT_TEXT_LIMIT = 1_000;
+const WORK_LIST_REVISION_SUMMARY_LIMIT = 300;
+const WORK_LIST_EVENT_REVISIONS = 20;
 const WORK_LIST_MAX_TEXT_LIMIT = 2_000;
 const WORK_LIST_STATUSES = [
     'pending',
@@ -86,15 +90,37 @@ function workListAsOf(value) {
  * takes: on 2026-09-29 the agent passed "2026-09-29T00:00:00+09:00" and the call failed.
  */
 function workListTime(value, field) {
-    if (typeof value === 'string' && /(?:Z|[+-]\d{2}:\d{2})$/.test(value)) {
-        const parsed = Date.parse(value);
-        if (Number.isFinite(parsed) && parsed >= 0)
-            return parsed;
-    }
+    const parsed = offsetIsoTime(value);
+    if (parsed !== undefined)
+        return parsed;
     if (Number.isSafeInteger(value) && value >= 0)
         return value;
     throw new Error(`work.list ${field} must be epoch milliseconds or an ISO time with its offset`);
 }
+const OFFSET_ISO_PATTERN = '^(\\d{4})-(\\d{2})-(\\d{2})[T ](\\d{2}):(\\d{2})(?::\\d{2}(?:\\.\\d{1,3})?)?(Z|([+-])(\\d{2}):(\\d{2}))$';
+/** An ISO time that states its offset (Z or ±HH:MM), as epoch ms; undefined for anything else. */
+function offsetIsoTime(value) {
+    const match = typeof value === 'string' ? new RegExp(OFFSET_ISO_PATTERN).exec(value) : null;
+    if (!match)
+        return undefined;
+    const parsed = Date.parse(match[0].replace(' ', 'T'));
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return undefined;
+    // Date.parse rolls an impossible date or hour forward (Feb 30 becomes Mar 2): the wall time
+    // at the stated offset must read back as written.
+    const [, year, month, day, hour, minute, zone, sign, offsetHours, offsetMinutes] = match;
+    const offset = zone === 'Z' ? 0 : (sign === '-' ? -1 : 1) * (Number(offsetHours) * 60 + Number(offsetMinutes));
+    const wall = new Date(parsed + offset * 60_000);
+    const readBack = [
+        wall.getUTCFullYear(),
+        wall.getUTCMonth() + 1,
+        wall.getUTCDate(),
+        wall.getUTCHours(),
+        wall.getUTCMinutes(),
+    ];
+    const written = [year, month, day, hour, minute].map(Number);
+    return readBack.every((part, index) => part === written[index]) ? parsed : undefined;
+}
 function workListFilter(input) {
     const status = workListStatuses(input.status);
     return {
@@ -110,8 +136,39 @@ function workListFilter(input) {
             ? {}
             : { changedBefore: workListTime(input.changedBefore, 'changedBefore') }),
         ...(input.due === undefined ? {} : { due: workListDueFilter(input.due) }),
+        ...(input.eventSince === undefined
+            ? {}
+            : { eventSince: workListTime(input.eventSince, 'eventSince') }),
+        ...(input.eventBefore === undefined
+            ? {}
+            : { eventBefore: workListTime(input.eventBefore, 'eventBefore') }),
+    };
+}
+/** An item's revisions in the span, the newest 20 with the count: one item moved 51 times in a day. */
+function workListEventPage(item, filter) {
+    const revisions = workListEventRevisions(item, filter);
+    return {
+        revisions: revisions.slice(-WORK_LIST_EVENT_REVISIONS),
+        revisionsTotal: revisions.length,
     };
 }
+function workListEventBounded(filter) {
+    return filter.eventSince !== undefined || filter.eventBefore !== undefined;
+}
+/** The revisions in the event bounds; a revision with no event time counts at its write time. */
+function workListEventRevisions(item, filter) {
+    return (item.chain ?? []).flatMap((entry) => {
+        const at = entry.eventDatetime ?? entry.createdAt;
+        if (filter.eventSince !== undefined && at < filter.eventSince)
+            return [];
+        if (filter.eventBefore !== undefined && at >= filter.eventBefore)
+            return [];
+        const summary = entry.summary !== null && entry.summary.length > WORK_LIST_REVISION_SUMMARY_LIMIT
+            ? `${entry.summary.slice(0, WORK_LIST_REVISION_SUMMARY_LIMIT - 1)}…`
+            : entry.summary;
+        return [{ revision: entry.revision, at, status: entry.status, stage: entry.stage, summary }];
+    });
+}
 function workListDueFilter(value) {
     if (typeof value !== 'string' || !WORK_LIST_DUE.includes(value)) {
         throw new Error(`work.list due must be one of ${WORK_LIST_DUE.join('|')}`);
@@ -280,6 +337,8 @@ function workListMatches(item, filter, now, timeZone) {
         return false;
     if (filter.due !== undefined && workListDueGroup(item, now, timeZone) !== filter.due)
         return false;
+    if (workListEventBounded(filter) && workListEventRevisions(item, filter).length === 0)
+        return false;
     return true;
 }
 function workListDueGroup(item, now, timeZone) {
@@ -332,6 +391,8 @@ function workListFingerprint(filter, dueDay) {
         filter.changedSince ?? null,
         filter.changedBefore ?? null,
         filter.due ?? null,
+        filter.eventSince ?? null,
+        filter.eventBefore ?? null,
     ]))
         .digest('base64url')
         .slice(0, 22);
@@ -355,7 +416,8 @@ function workListReadSnapshot(ctx, filter) {
     let cursor;
     for (;;) {
         const query = {
-            history: 'current',
+            // The chain carries each revision's event time and summary, read only for an event span.
+            history: workListEventBounded(filter) ? 'chain' : 'current',
             limit: 100,
             ...(filter.asOf === undefined ? {} : { asOf: filter.asOf }),
             ...(cursor === undefined ? {} : { cursor }),
@@ -494,6 +556,94 @@ function workListDetailRecord(item, textOffset, textLimit, historyOffset, now, t
         latestJudgmentRef: item.latestJudgmentRef,
     };
 }
+/**
+ * One step of the walk: every link written from or to any revision of the item, with the relation,
+ * the reason, who wrote it, its evidence, any later correction, and the other end. A link sits on
+ * the revision that wrote it, so every revision is a seed; source citations (derived_from) and the
+ * item's own records are left out, and a correction shows on the link it corrects.
+ */
+function workListLinks(input, ctx) {
+    const ids = workListDetailIds(input.ids);
+    const items = [];
+    const missingIds = [];
+    const otherItems = new Map();
+    for (const id of ids) {
+        const page = ctx.knowledge.readWork({ history: 'all', ...(typeof id === 'number' ? { rowId: id } : { commitmentId: id }) }, ctx.access);
+        const item = page.items[0];
+        if (item === undefined || item.history === undefined) {
+            missingIds.push(id);
+            continue;
+        }
+        const own = new Set(item.history.map((revision) => revision.recordRef.id));
+        const graph = ctx.knowledge.queryGraph({
+            view: 'neighbors',
+            seeds: item.history.map((revision) => revision.recordRef),
+            maxDepth: 1,
+            direction: 'both',
+            relations: knowledge_1.TWIN_EDGE_TYPES.filter((relation) => relation !== 'derived_from'),
+            history: 'all',
+            limit: 500,
+        }, ctx.access);
+        const nodes = new Map(graph.nodes.map((node) => [`${node.ref.kind}:${node.ref.id}`, node]));
+        const links = [];
+        for (const edge of graph.edges) {
+            const out = own.has(edge.from.id);
+            if (!out && !own.has(edge.to.id))
+                continue;
+            const other = out ? edge.to : edge.from;
+            if (other.kind === 'edge' || (other.kind === 'memory' && own.has(other.id)))
+                continue;
+            const attrs = (edge.attrs ?? {});
+            const written = (attrs.relation_attrs ?? {});
+            const node = nodes.get(`${other.kind}:${other.id}`);
+            const data = node?.data;
+            const commitmentId = other.kind === 'memory' ? data?.work?.commitmentId : undefined;
+            if (commitmentId !== undefined && commitmentId === item.commitmentId)
+                continue;
+            const reason = typeof written.reason === 'string'
+                ? written.reason
+                : typeof attrs.reason_text === 'string'
+                    ? attrs.reason_text
+                    : null;
+            links.push({
+                edgeId: edge.id,
+                relation: edge.relation,
+                direction: out ? 'out' : 'in',
+                reason,
+                ...(typeof written.role === 'string' ? { role: written.role } : {}),
+                source: attrs.source ?? null,
+                ...(attrs.evidence_refs ? { evidenceRefs: attrs.evidence_refs } : {}),
+                ...(attrs.corrected_by ? { correctedBy: attrs.corrected_by } : {}),
+                other: commitmentId !== undefined
+                    ? { kind: 'work', commitmentId }
+                    : { kind: other.kind, id: other.id, name: node?.label ?? null },
+            });
+            if (commitmentId !== undefined)
+                otherItems.set(commitmentId, {});
+        }
+        items.push({
+            commitmentId: item.commitmentId,
+            title: workListText(workListValueObject(item.values).title),
+            revisions: item.history.length,
+            links,
+            coverage: graph.coverage,
+        });
+    }
+    // The other items' current title and status, so the next step can be chosen without opening them.
+    for (const commitmentId of otherItems.keys()) {
+        const found = ctx.knowledge.readWork({ commitmentId }, ctx.access).items[0];
+        if (found !== undefined)
+            otherItems.set(commitmentId, {
+                title: workListText(workListValueObject(found.values).title),
+                status: workListStatus(found),
+            });
+    }
+    for (const item of items)
+        for (const link of item.links)
+            if (link.other.kind === 'work')
+                Object.assign(link.other, otherItems.get(link.other.commitmentId) ?? {});
+    return { success: true, view: 'links', items, missingIds };
+}
 function workListDetail(input, ctx) {
     const ids = workListDetailIds(input.ids);
     const textOffset = workListNonNegativeInteger(input.text_offset, 'text_offset', 0);
@@ -582,14 +732,20 @@ function workListOverview(snapshot, rankedItems, now, timeZone) {
 async function runWorkListView(rawInput, ctx) {
     const input = workListObject(rawInput);
     const view = input.view === undefined ? 'items' : input.view;
-    if (view !== 'overview' && view !== 'items' && view !== 'detail' && view !== 'pipeline') {
-        throw new Error('work.list view must be one of overview|items|detail|pipeline');
+    if (view !== 'overview' &&
+        view !== 'items' &&
+        view !== 'detail' &&
+        view !== 'pipeline' &&
+        view !== 'links') {
+        throw new Error('work.list view must be one of overview|items|detail|pipeline|links');
     }
-    if (input.ids !== undefined && view !== 'detail') {
-        throw new Error('work.list ids are only valid with view=detail');
+    if (input.ids !== undefined && view !== 'detail' && view !== 'links') {
+        throw new Error('work.list ids are only valid with view=detail or view=links');
     }
     if (view === 'detail')
         return workListDetail(input, ctx);
+    if (view === 'links')
+        return workListLinks(input, ctx);
     const requested = workListFilter(input);
     const filter = input.cursor !== undefined && Object.keys(requested).length === 0
         ? (workListCursorQuery(input.cursor) ?? requested)
@@ -657,7 +813,10 @@ async function runWorkListView(rawInput, ctx) {
     return {
         success: true,
         view: 'items',
-        tasks: page.map(({ item, score }) => workListCompact(item, now, score, ctx.timeZone)),
+        tasks: page.map(({ item, score }) => ({
+            ...workListCompact(item, now, score, ctx.timeZone),
+            ...(workListEventBounded(filter) ? workListEventPage(item, filter) : {}),
+        })),
         total: rankedItems.length,
         returned: page.length,
         nextCursor: nextOffset === null
@@ -680,12 +839,12 @@ function workListActionRegistrations(ports) {
         {
             contract: {
                 name: 'work.list',
-                summary: 'Find owner work by what the turn needs: items filtered by status, stage, project, due, changedSince or changedBefore and ranked by text, in pages of 25 (50 max); overview counts; detail for up to 4 ids with the current record, its 20 newest evidence refs and its 5 newest revisions (history_offset pages older ones). pipeline returns every open item grouped by stage (rows in the order of its fields: commitmentId, title, status, assignee, deadline, latest_change in epoch seconds, latest_event) and ignores limit: read it inside a script that builds the board, not into your context.',
+                summary: 'Find owner work by what the turn needs: items filtered by status, stage, project, due, changedSince or changedBefore and ranked by text, in pages of 25 (50 max); overview counts; detail for up to 4 ids with the current record, its 20 newest evidence refs and its 5 newest revisions (history_offset pages older ones). eventSince and eventBefore find what happened in a span by source event time, each item with its revisions there. pipeline returns every open item grouped by stage (rows in the order of its fields: commitmentId, title, status, assignee, deadline, latest_change in epoch seconds, latest_event) and ignores limit: read it inside a script that builds the board, not into your context. links for up to 4 ids returns every link from or to the item with its relation, reason, writer, evidence, correction and the other end (item title and status, person, record or observation); follow it to the other item with detail.',
                 inputSchema: {
                     type: 'object',
                     additionalProperties: false,
                     properties: {
-                        view: { type: 'string', enum: ['overview', 'items', 'detail', 'pipeline'] },
+                        view: { type: 'string', enum: ['overview', 'items', 'detail', 'pipeline', 'links'] },
                         ids: {
                             type: 'array',
                             minItems: 1,
@@ -733,6 +892,20 @@ function workListActionRegistrations(ports) {
                             enum: WORK_LIST_DUE,
                             description: "Open items whose deadline is past, is the owner's today, is later, or is unset.",
                         },
+                        eventSince: {
+                            oneOf: [
+                                { type: 'integer', minimum: 0 },
+                                { type: 'string', minLength: 1 },
+                            ],
+                            description: 'Only items with a revision whose source event time is at or after this time (epoch ms or ISO with offset); each item lists those revisions with their summaries.',
+                        },
+                        eventBefore: {
+                            oneOf: [
+                                { type: 'integer', minimum: 0 },
+                                { type: 'string', minLength: 1 },
+                            ],
+                            description: 'Only items with a revision whose source event time is before this time; with eventSince, what happened on a day.',
+                        },
                         text_offset: { type: 'integer', minimum: 0 },
                         text_limit: { type: 'integer', minimum: 1, maximum: WORK_LIST_MAX_TEXT_LIMIT },
                         history_offset: {
@@ -883,8 +1056,8 @@ const commandFields = {
         items: catalog_1.recordLinkSchema,
     },
     eventDatetime: {
-        description: 'Source event time as epoch milliseconds, not replay time, or null, e.g. 1760000000000.',
-        oneOf: [{ type: 'number' }, { type: 'null' }],
+        description: 'Source event time as epoch milliseconds or an ISO time with its offset, not replay time, or null, e.g. 1760000000000 or "2026-01-01T09:30:00+09:00".',
+        oneOf: [{ type: 'number' }, { type: 'string', pattern: OFFSET_ISO_PATTERN }, { type: 'null' }],
     },
     recordedAt: {
         type: 'number',
@@ -948,6 +1121,18 @@ function assertSourceRefsExist(body, ports) {
         }
     }
 }
+/**
+ * The ledger stores eventDatetime as epoch ms. On 2026-09-29 an agent passed the source time as
+ * "…T12:30:00+09:00", the write was refused, and the record order ended without a record.
+ */
+function withEventEpoch(body, action) {
+    if (typeof body.eventDatetime !== 'string')
+        return body;
+    const eventDatetime = offsetIsoTime(body.eventDatetime);
+    if (eventDatetime === undefined)
+        throw new knowledge_1.JudgmentError('INVALID_COMMAND', `${action} eventDatetime must be epoch milliseconds or an ISO time with its offset`);
+    return { ...body, eventDatetime };
+}
 function commandFieldsFrom(body) {
     const { commitmentId: _commitmentId, expectedRevision: _expectedRevision, ...fields } = body;
     return fields;
@@ -989,7 +1174,7 @@ function minimalWorkActionRegistrations(ports) {
                 ],
             },
             exec: (input, context) => {
-                const body = input;
+                const body = withEventEpoch(input, 'work.create');
                 assertReplayEventDatetime(body, context, 'work.create');
                 assertSourceRefsExist(body, ports);
                 return ports.knowledge.createWork({
@@ -1019,7 +1204,7 @@ function minimalWorkActionRegistrations(ports) {
                 ],
             },
             exec: (input, context) => {
-                const body = input;
+                const body = withEventEpoch(input, 'work.revise');
                 assertReplayEventDatetime(body, context, 'work.revise');
                 assertSourceRefsExist(body, ports);
                 const commitmentId = body.commitmentId;
@@ -1034,6 +1219,140 @@ function minimalWorkActionRegistrations(ports) {
                 }, context.access);
             },
         },
+        workLinkRegistration(ports),
     ];
 }
+// Replacing and amending change the target's state and are written with a revision (work.revise
+// links, memory.retire), not as a bare link.
+const LINK_RELATIONS = [
+    'builds_on',
+    'refines',
+    'contradicts',
+    'debates',
+    'synthesizes',
+    'mentions',
+    'blocks',
+    'next_action_for',
+];
+const linkSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['from', 'to', 'relation', 'reason'],
+    properties: {
+        from: {
+            type: 'string',
+            description: 'commitmentId of the item the link is stated from, e.g. "commitment_123".',
+        },
+        to: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['kind', 'id'],
+            properties: {
+                kind: {
+                    type: 'string',
+                    enum: ['work', 'memory', 'registry', 'observation', 'edge'],
+                    description: 'What the other end is, e.g. "work".',
+                },
+                id: {
+                    type: 'string',
+                    minLength: 1,
+                    description: 'Its id: a commitmentId, record id, node id, observationRef or edgeId.',
+                },
+            },
+            description: 'The other end: an item by commitmentId (kind work), one record, a person node, an observation, or a link (kind edge) the new link contradicts, e.g. {"kind":"work","id":"commitment_456"}.',
+        },
+        relation: {
+            type: 'string',
+            enum: [...LINK_RELATIONS],
+            description: 'builds_on for an earlier case or work this continues, refines for a correction, contradicts for a reversal or a wrong link, e.g. "builds_on".',
+        },
+        reason: {
+            type: 'string',
+            minLength: 1,
+            description: 'What relates the two, in a sentence the next reader can check, e.g. "The same setup problem; it ended in a client FIX after the setup was redone".',
+        },
+        evidenceRefs: {
+            type: 'array',
+            items: { type: 'string', minLength: 1 },
+            description: 'observationRefs the reason rests on, e.g. ["obs_123"].',
+        },
+    },
+};
+function headRecord(ports, commitmentId, access) {
+    const item = ports.knowledge.readWork({ commitmentId }, access).items[0];
+    if (item === undefined)
+        throw new knowledge_1.JudgmentError('REFERENCE_NOT_FOUND', `Commitment is unavailable: ${commitmentId}`);
+    return { kind: 'memory', id: item.latestJudgmentRef.id };
+}
+function workLinkRegistration(ports) {
+    return {
+        contract: {
+            name: 'work.link',
+            recallableWrite: true,
+            summary: 'Link one work item to another item, a record, a person or an observation, with the reason you judged; it appends an edge and writes no revision. A link to a link (to.kind edge, relation contradicts) corrects it: the wrong link stays in the history with the correction beside it.',
+            inputSchema: linkSchema,
+            examples: [
+                {
+                    title: 'Link an earlier case of the same kind',
+                    input: {
+                        from: 'commitment-reference',
+                        to: { kind: 'work', id: 'commitment-earlier' },
+                        relation: 'builds_on',
+                        reason: 'what is the same and how the earlier one ended',
+                    },
+                },
+            ],
+        },
+        exec: (input, context) => {
+            const body = input;
+            for (const ref of body.evidenceRefs ?? []) {
+                if (!ports.observationExists(ref))
+                    throw new knowledge_1.JudgmentError('REFERENCE_NOT_FOUND', `evidenceRefs names an unavailable observation: ${ref}`);
+            }
+            // A retried call finds its link before the heads are read again: the item may have been
+            // revised since, and the retry must still return the same link. The ends are compared as
+            // revisions of the named items; core's content hash compares the rest of the statement.
+            const commandId = operationId(context, 'work.link');
+            const earlier = ports.knowledge.findLink(commandId, context.access);
+            let from;
+            let to;
+            if (earlier) {
+                const isRevisionOf = (ref, commitmentId) => ref.kind === 'memory' &&
+                    (ports.knowledge.readWork({ commitmentId, history: 'all' }, context.access).items[0]
+                        ?.history ?? []).some((revision) => revision.recordRef.id === ref.id);
+                const sameTarget = body.to.kind === 'work'
+                    ? isRevisionOf(earlier.to, body.to.id)
+                    : earlier.to.kind === body.to.kind && earlier.to.id === body.to.id;
+                if (!isRevisionOf(earlier.from, body.from) || !sameTarget)
+                    throw new knowledge_1.JudgmentError('COMMAND_CONFLICT', 'The command id is already bound to another link');
+                from = earlier.from;
+                to = earlier.to;
+            }
+            else {
+                from = headRecord(ports, body.from, context.access);
+                to =
+                    body.to.kind === 'work'
+                        ? headRecord(ports, body.to.id, context.access)
+                        : { kind: body.to.kind, id: body.to.id };
+            }
+            const receipt = ports.knowledge.appendLink({
+                commandId,
+                from,
+                to,
+                relation: body.relation,
+                reason: body.reason,
+                ...(body.evidenceRefs?.length
+                    ? {
+                        evidenceRefs: body.evidenceRefs.map((id) => ({
+                            kind: 'observation',
+                            id,
+                        })),
+                    }
+                    : {}),
+                modelRunId: context.session?.modelRunId ?? null,
+            }, context.access);
+            return { ...receipt, from: { commitmentId: body.from, recordRef: from }, to };
+        },
+    };
+}
 //# sourceMappingURL=work-actions.js.map