@meetquinn/animactl 0.1.21 → 0.1.22-canary.563.1.0620c02

package/dist/server/inbox/observed-conversation.d.ts

@@ -0,0 +1,24 @@
+import { type SlackRawFile } from '../slack/slack.helper.js';
+import { type ObservedFileDescriptor, type ObserveSlackMessageResult } from '../storage/schema/observed-conversation.store.js';
+import { type ObservableSlackMessage, type SlackMessageEnvelope, type SlackRawMessageEvent } from './slack-events.js';
+export declare function observeObservableSlackMessage(input: {
+    agentId: string;
+    envelope?: SlackMessageEnvelope;
+    event: ObservableSlackMessage;
+    /** When true, rethrow store failures after marking continuity degraded. Default: mark degraded and continue. */
+    throwOnError?: boolean;
+}): Promise<ObserveSlackMessageResult | undefined>;
+/**
+ * Ingress entry: if the raw event is observable, journal it (fail-soft by
+ * default). Returns whether observation was attempted.
+ */
+export declare function observeSlackEventAtIngress(input: {
+    agentId: string;
+    envelope?: SlackMessageEnvelope;
+    event: SlackRawMessageEvent;
+    throwOnError?: boolean;
+}): Promise<ObserveSlackMessageResult | undefined>;
+/** @deprecated Use observeObservableSlackMessage / observeSlackEventAtIngress. */
+export declare const observeRoutableSlackMessage: typeof observeObservableSlackMessage;
+export declare function observedFilesFromSlack(files: SlackRawFile[] | undefined): ObservedFileDescriptor[];
+//# sourceMappingURL=observed-conversation.d.ts.map

package/dist/server/inbox/observed-conversation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observed-conversation.d.ts","sourceRoot":"","sources":["../../../server/inbox/observed-conversation.ts"],"names":[],"mappings":"AAOA,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC/B,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AAE3B,wBAAsB,6BAA6B,CAAC,KAAK,EAAE;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,KAAK,EAAE,sBAAsB,CAAC;IAC9B,gHAAgH;IAChH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC,CAwBjD;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,CAAC,KAAK,EAAE;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,KAAK,EAAE,oBAAoB,CAAC;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC,CAQjD;AAED,kFAAkF;AAClF,eAAO,MAAM,2BAA2B,sCAAgC,CAAC;AAEzE,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,YAAY,EAAE,GAAG,SAAS,GAChC,sBAAsB,EAAE,CAc1B"}

package/dist/server/inbox/observed-conversation.js

@@ -0,0 +1,69 @@
+// Slack ingress helper: record an observable message into the agent-scoped
+// observed-conversation journal before wake/subscription filtering.
+//
+// Observation uses a broader predicate than runtime routability: userless
+// bot_message and file-only posts are journaled without changing wake routing.
+import { errorMessage } from '../ids.js';
+import { slackTsToIso } from '../slack/slack.helper.js';
+import { observedConversationStoreForAgent, } from '../storage/schema/observed-conversation.store.js';
+import { isObservableSlackMessage, slackEventTeamId, } from './slack-events.js';
+export async function observeObservableSlackMessage(input) {
+    const teamId = slackEventTeamId(input.envelope, input.event);
+    const store = observedConversationStoreForAgent(input.agentId);
+    const files = observedFilesFromSlack(input.event.files);
+    try {
+        return await store.observe({
+            ...(input.event.bot_id ? { botId: input.event.bot_id } : {}),
+            channelId: input.event.channel,
+            ...(files.length > 0 ? { files } : {}),
+            messageTs: input.event.ts,
+            ...(slackTsToIso(input.event.ts) ? { receivedAt: slackTsToIso(input.event.ts) } : {}),
+            teamId,
+            text: input.event.text ?? '',
+            ...(input.event.thread_ts ? { threadTs: input.event.thread_ts } : {}),
+            ...(input.event.user ? { userId: input.event.user } : {}),
+        });
+    }
+    catch (error) {
+        // store.observe already marks continuity degraded; helper only controls throw.
+        if (input.throwOnError)
+            throw error;
+        console.warn(`observed-conversation journal write failed for agent=${input.agentId} channel=${input.event.channel} ts=${input.event.ts}: ${errorMessage(error)}`);
+        return undefined;
+    }
+}
+/**
+ * Ingress entry: if the raw event is observable, journal it (fail-soft by
+ * default). Returns whether observation was attempted.
+ */
+export async function observeSlackEventAtIngress(input) {
+    if (!isObservableSlackMessage(input.event))
+        return undefined;
+    return observeObservableSlackMessage({
+        agentId: input.agentId,
+        envelope: input.envelope,
+        event: input.event,
+        ...(input.throwOnError ? { throwOnError: true } : {}),
+    });
+}
+/** @deprecated Use observeObservableSlackMessage / observeSlackEventAtIngress. */
+export const observeRoutableSlackMessage = observeObservableSlackMessage;
+export function observedFilesFromSlack(files) {
+    if (!Array.isArray(files) || files.length === 0)
+        return [];
+    const out = [];
+    for (const file of files) {
+        if (!file || typeof file.id !== 'string' || file.id.trim().length === 0)
+            continue;
+        const descriptor = { id: file.id };
+        if (typeof file.name === 'string' && file.name.length > 0)
+            descriptor.name = file.name;
+        else if (typeof file.title === 'string' && file.title.length > 0)
+            descriptor.name = file.title;
+        if (typeof file.mimetype === 'string' && file.mimetype.length > 0) {
+            descriptor.mimetype = file.mimetype;
+        }
+        out.push(descriptor);
+    }
+    return out;
+}

package/dist/server/inbox/slack-events.d.ts

@@ -35,6 +35,20 @@ export interface RoutableSlackMessage extends SlackRawMessageEvent {
     type: 'app_mention' | 'message';
     user: string;
 }
+/**
+ * Observable for the local observed-conversation journal — broader than runtime
+ * routability. Captures userless `bot_message` (bot_id only) and file-only posts
+ * without requiring a human `user`. Wake routing still uses isRoutableSlackMessage.
+ */
+export interface ObservableSlackMessage extends SlackRawMessageEvent {
+    channel: string;
+    ts: string;
+    type: 'app_mention' | 'message';
+    /** At least one of user / bot_id is present (enforced by the predicate). */
+    bot_id?: string;
+    user?: string;
+}
+export declare function isObservableSlackMessage(event: SlackRawMessageEvent): event is ObservableSlackMessage;
 export declare function isRoutableSlackMessage(event: SlackRawMessageEvent): event is RoutableSlackMessage;
 export declare function slackEventTeamId(envelope: SlackMessageEnvelope | undefined, event: SlackRawMessageEvent): string;
 export declare function normalizeSlackMessage(input: {

package/dist/server/inbox/slack-events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slack-events.d.ts","sourceRoot":"","sources":["../../../server/inbox/slack-events.ts"],"names":[],"mappings":"AACA,OAAO,EAA0C,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAGrG,OAAO,KAAK,EAAmB,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,SAAS,GAAG,IAAI,GAAG,QAAQ,CAAC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,SAAS,GAAG,QAAQ,CAAC;CAClC;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAqB,SAAQ,oBAAoB;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,aAAa,GAAG,SAAS,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,oBAAoB,GAAG,KAAK,IAAI,oBAAoB,CAUjG;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,oBAAoB,GAAG,SAAS,EAC1C,KAAK,EAAE,oBAAoB,GAC1B,MAAM,CAER;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,oBAAoB,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,gBAAgB,CAAC;CAChC,GAAG,cAAc,CA2BjB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAEpE;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAEpE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,CAcxE"}
+{"version":3,"file":"slack-events.d.ts","sourceRoot":"","sources":["../../../server/inbox/slack-events.ts"],"names":[],"mappings":"AACA,OAAO,EAA0C,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAGrG,OAAO,KAAK,EAAmB,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,SAAS,GAAG,IAAI,GAAG,QAAQ,CAAC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,SAAS,GAAG,QAAQ,CAAC;CAClC;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAqB,SAAQ,oBAAoB;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,aAAa,GAAG,SAAS,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAuB,SAAQ,oBAAoB;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,aAAa,GAAG,SAAS,CAAC;IAChC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,oBAAoB,GAAG,KAAK,IAAI,sBAAsB,CAcrG;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,oBAAoB,GAAG,KAAK,IAAI,oBAAoB,CAUjG;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,oBAAoB,GAAG,SAAS,EAC1C,KAAK,EAAE,oBAAoB,GAC1B,MAAM,CAER;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,oBAAoB,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,gBAAgB,CAAC;CAChC,GAAG,cAAc,CA2BjB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAEpE;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAEpE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,CAcxE"}

package/dist/server/inbox/slack-events.js

@@ -2,6 +2,24 @@ import { nowIso, slackMessageEventId, slackSurfaceId } from '../ids.js';
 import { normalizeSlackEventFiles, slackTsToIso } from '../slack/slack.helper.js';
 import { slackMessagePreviewsFromAttachments } from '../slack/message-previews.js';
 import { slackVisibleMessageText } from '../slack/message-text.js';
+export function isObservableSlackMessage(event) {
+    if (event.type !== 'message' && event.type !== 'app_mention')
+        return false;
+    if (typeof event.channel !== 'string' || typeof event.ts !== 'string')
+        return false;
+    if (event.subtype !== undefined && event.subtype !== 'bot_message' && event.subtype !== 'file_share') {
+        return false;
+    }
+    const hasUser = typeof event.user === 'string' && event.user.length > 0;
+    const hasBot = typeof event.bot_id === 'string' && event.bot_id.length > 0;
+    if (!hasUser && !hasBot)
+        return false;
+    // text may be missing on bot_message; empty + files still counts.
+    const text = typeof event.text === 'string' ? event.text : '';
+    const hasText = text.trim().length > 0;
+    const hasFiles = Array.isArray(event.files) && event.files.length > 0;
+    return hasText || hasFiles;
+}
 export function isRoutableSlackMessage(event) {
     return ((event.type === 'message' || event.type === 'app_mention') &&
         typeof event.channel === 'string' &&

package/dist/server/inbox/slack-subscriber.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slack-subscriber.d.ts","sourceRoot":"","sources":["../../../server/inbox/slack-subscriber.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAmC5D,OAAO,EAAE,gBAAgB,EAA+B,MAAM,yBAAyB,CAAC;AAExF,MAAM,WAAW,2BAA2B;IAC1C,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,uGAAuG;IACvG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAED,qBAAa,oBAAoB;IAQnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAPpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAuB;IACvD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA8B;IAG5D,OAAO,CAAC,0BAA0B,CAAS;gBAEd,OAAO,EAAE,2BAA2B;IAO3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,OAAO,CAAC,SAAS;YAgFH,oBAAoB;YASpB,qBAAqB;YAOrB,0BAA0B;YA2C1B,kCAAkC;YAYlC,gBAAgB;IAgE9B,OAAO,CAAC,uBAAuB;CAYhC;AAED,wBAAgB,iCAAiC,CAAC,KAAK,EAAE;IACvD,IAAI,EAAE,cAAc,CAAC;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IAC3E,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,CAAC;CACpD,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB"}
+{"version":3,"file":"slack-subscriber.d.ts","sourceRoot":"","sources":["../../../server/inbox/slack-subscriber.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAoC5D,OAAO,EAAE,gBAAgB,EAA+B,MAAM,yBAAyB,CAAC;AAExF,MAAM,WAAW,2BAA2B;IAC1C,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,uGAAuG;IACvG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAED,qBAAa,oBAAoB;IAQnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAPpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAuB;IACvD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA8B;IAG5D,OAAO,CAAC,0BAA0B,CAAS;gBAEd,OAAO,EAAE,2BAA2B;IAO3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,OAAO,CAAC,SAAS;YAgFH,oBAAoB;YASpB,qBAAqB;YAOrB,0BAA0B;YA2C1B,kCAAkC;YAYlC,gBAAgB;IA2E9B,OAAO,CAAC,uBAAuB;CAYhC;AAED,wBAAgB,iCAAiC,CAAC,KAAK,EAAE;IACvD,IAAI,EAAE,cAAc,CAAC;IACrB,WAAW,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IAC3E,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,CAAC;CACpD,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB"}

package/dist/server/inbox/slack-subscriber.js

@@ -13,6 +13,7 @@ import { withCanonicalSlackVisibleText } from '../slack/message-text.js';
 import { isSlackEvent, isRoutableSlackMessage, slackEventTeamId, slackSurfaceForEvent, } from './slack-events.js';
 import { slackAttentionSuggestionPayload, } from './attention-suggestion-activity.js';
 import { runIngestPipeline } from './ingest-pipeline.js';
+import { observeSlackEventAtIngress } from './observed-conversation.js';
 import { buildSlackInboxItemWithLatePreview } from './slack-ingest.js';
 import { slackShortcutHandoffServiceForAgent } from './slack-shortcut-handoff.service.js';
 import { slackRuntimeDecision } from './slack-subscription.service.js';
@@ -192,9 +193,18 @@ export class SlackInboxSubscriber {
         // `text` can truncate before a trailing user mention; enrichment after an
         // ignore never runs, so mention detection must see the full body first.
         const rawEvent = withCanonicalSlackVisibleText(event);
+        const envelope = body;
+        // Observed-conversation journal (send-hold cut a): record every observable
+        // Slack message this agent process sees — including userless bot_message —
+        // BEFORE wake/subscription filtering and BEFORE isRoutableSlackMessage.
+        // Failures mark continuity degraded and never block routing.
+        await observeSlackEventAtIngress({
+            agentId: this.options.queue.agentId,
+            envelope,
+            event: rawEvent,
+        });
         if (!isRoutableSlackMessage(rawEvent))
             return;
-        const envelope = body;
         const teamId = slackEventTeamId(envelope, rawEvent);
         let latePreview;
         await runIngestPipeline({

package/dist/server/storage/schema/observed-conversation.store.d.ts

@@ -0,0 +1,212 @@
+import { z } from 'zod';
+/** Bound recent dedupe window inside one conversation journal. */
+export declare const OBSERVED_CONVERSATION_DEDUPE_RECENT = 2000;
+/** Cap retained journal archives per conversation (plus the live segment). */
+export declare const OBSERVED_CONVERSATION_MAX_ARCHIVES = 4;
+/** Minimal local file descriptor for file-only / file-bearing messages. */
+export declare const ObservedFileDescriptorSchema: z.ZodObject<{
+    id: z.ZodString;
+    mimetype: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ObservedFileDescriptor = z.infer<typeof ObservedFileDescriptorSchema>;
+export declare const ObservedConversationEntrySchema: z.ZodObject<{
+    botId: z.ZodOptional<z.ZodString>;
+    channelId: z.ZodString;
+    eventId: z.ZodString;
+    files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        mimetype: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    messageTs: z.ZodString;
+    observedAt: z.ZodString;
+    ordinal: z.ZodNumber;
+    receivedAt: z.ZodString;
+    surfaceId: z.ZodString;
+    teamId: z.ZodString;
+    text: z.ZodString;
+    threadTs: z.ZodOptional<z.ZodString>;
+    userId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ObservedConversationEntry = z.infer<typeof ObservedConversationEntrySchema>;
+/** Journal-tail metadata for one conversation (not the delivered cursor). */
+export declare const ConversationIndexSchema: z.ZodObject<{
+    lastEventId: z.ZodString;
+    lastMessageTs: z.ZodString;
+    surfaceId: z.ZodString;
+    tailOrdinal: z.ZodNumber;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type ConversationIndex = z.infer<typeof ConversationIndexSchema>;
+/**
+ * Delivered cursor record.
+ *
+ * - `deliveredOrdinal: null` → **confirmed absent** (never delivered into this
+ *   conversation; "no-cursor lands" applies only to this state).
+ * - `deliveredOrdinal: 0` → present at origin (established, nothing past start).
+ * - `deliveredOrdinal: N>0` → delivered through ordinal N inclusive.
+ *
+ * A missing cursor file reads as confirmed absent via empty().
+ */
+export declare const ConversationCursorRecordSchema: z.ZodObject<{
+    deliveredOrdinal: z.ZodNullable<z.ZodNumber>;
+    lastDeliveredEventId: z.ZodOptional<z.ZodString>;
+    lastDeliveredMessageTs: z.ZodOptional<z.ZodString>;
+    surfaceId: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type ConversationCursorRecord = z.infer<typeof ConversationCursorRecordSchema>;
+export type ConversationCursorView = {
+    status: 'absent';
+    surfaceId: string;
+} | {
+    status: 'present';
+    deliveredOrdinal: number;
+    lastDeliveredEventId?: string;
+    lastDeliveredMessageTs?: string;
+    surfaceId: string;
+    updatedAt: string;
+};
+export type AdvanceCursorExpected = {
+    status: 'absent';
+} | {
+    status: 'present';
+    deliveredOrdinal: number;
+};
+export type AdvanceCursorResult = {
+    advanced: true;
+    cursor: Extract<ConversationCursorView, {
+        status: 'present';
+    }>;
+} | {
+    advanced: false;
+    reason: 'cas_mismatch' | 'regression' | 'beyond_tail';
+    cursor: ConversationCursorView;
+    /** Reconciled journal tail when reason is beyond_tail (0 if no observations). */
+    tailOrdinal?: number;
+};
+/** Agent-wide observation continuity (fail-closed signal for later send hold). */
+export declare const ObservationContinuitySchema: z.ZodObject<{
+    lastFailureAt: z.ZodOptional<z.ZodString>;
+    lastFailureEventId: z.ZodOptional<z.ZodString>;
+    lastFailureMessage: z.ZodOptional<z.ZodString>;
+    lastFailureSurfaceId: z.ZodOptional<z.ZodString>;
+    lastSuccessAt: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        ok: "ok";
+        degraded: "degraded";
+    }>;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type ObservationContinuity = z.infer<typeof ObservationContinuitySchema>;
+export interface ObserveSlackMessageInput {
+    botId?: string;
+    channelId: string;
+    files?: ObservedFileDescriptor[];
+    messageTs: string;
+    /** ISO time derived from Slack ts when available. */
+    receivedAt?: string;
+    teamId: string;
+    text: string;
+    /** Thread parent ts for replies only; omit for top-level / DM root. */
+    threadTs?: string;
+    userId?: string;
+}
+export type ObserveSlackMessageResult = {
+    appended: true;
+    entry: ObservedConversationEntry;
+} | {
+    appended: false;
+    reason: 'duplicate';
+    entry?: ObservedConversationEntry;
+};
+export declare function observedConversationsDir(agentId: string): string;
+/** Stable filesystem key for a surface id (no path separators / nulls). */
+export declare function observedConversationFileStem(surfaceId: string): string;
+/**
+ * Explicit top-level vs thread partition: only true replies (thread_ts set and
+ * different from the message ts) join a thread surface. Channel parents and
+ * DM roots stay on the unthreaded surface.
+ */
+export declare function conversationThreadTs(input: {
+    messageTs: string;
+    threadTs?: string;
+}): string | undefined;
+export declare function surfaceIdForObservation(input: {
+    channelId: string;
+    messageTs: string;
+    teamId: string;
+    threadTs?: string;
+}): string;
+export declare function cursorViewFromRecord(surfaceId: string, record: ConversationCursorRecord): ConversationCursorView;
+/**
+ * Rebuild journal-tail index from retained journal rows when the index lags
+ * (append-then-index-write crash recovery).
+ */
+export declare function reconcileIndexFromJournal(current: ConversationIndex, recent: ObservedConversationEntry[], surfaceId: string): ConversationIndex;
+export interface ObservedConversationStoreOptions {
+    /** Journal rotation size; tests may pass a tiny value. */
+    maxBytes?: number;
+    maxArchives?: number;
+}
+export declare class ObservedConversationStore {
+    private readonly agentId;
+    private readonly options;
+    constructor(agentId: string, options?: ObservedConversationStoreOptions);
+    /**
+     * Record one Slack message observation. Idempotent on eventId within the
+     * conversation. Reconciles a stale index from the journal before assigning
+     * a new ordinal (crash recovery).
+     */
+    observe(input: ObserveSlackMessageInput): Promise<ObserveSlackMessageResult>;
+    getIndex(surfaceId: string): Promise<ConversationIndex | undefined>;
+    /**
+     * Read journal-tail index, reconciling from the retained journal when the
+     * stored index lags (same recovery path as observe).
+     */
+    getIndexReconciled(surfaceId: string): Promise<ConversationIndex | undefined>;
+    readJournal(surfaceId: string, options?: {
+        afterOrdinal?: number;
+        limit?: number;
+    }): Promise<ObservedConversationEntry[]>;
+    readTail(surfaceId: string, limit: number): Promise<ObservedConversationEntry[]>;
+    getCursor(surfaceId: string): Promise<ConversationCursorView>;
+    /**
+     * Monotonic CAS advance of the delivered cursor.
+     *
+     * - `expected` must match the current absent/present+ordinal view.
+     * - `nextDeliveredOrdinal` must be >= 0; if current is present, next must be
+     *   >= current.deliveredOrdinal (regression otherwise).
+     * - Fail-closed against the journal: next must be <= reconciled journal tail.
+     *   The only allowed advance with no observed rows is present@0 (thread-root
+     *   establishment). Anything above tail returns `beyond_tail`.
+     */
+    advanceCursor(input: {
+        expected: AdvanceCursorExpected;
+        lastDeliveredEventId?: string;
+        lastDeliveredMessageTs?: string;
+        nextDeliveredOrdinal: number;
+        surfaceId: string;
+    }): Promise<AdvanceCursorResult>;
+    getContinuity(): Promise<ObservationContinuity>;
+    markDegraded(input: {
+        eventId?: string;
+        message: string;
+        surfaceId?: string;
+    }): Promise<ObservationContinuity>;
+    /** Best-effort: never mask the observation error with a continuity write error. */
+    private markDegradedSafe;
+    /** Test/recovery helper: force-write journal-tail index without observing. */
+    writeIndexForTest(index: ConversationIndex): Promise<void>;
+    private journal;
+    private indexStore;
+    private cursorStore;
+    private continuityStore;
+    private journalPath;
+    private indexPath;
+    private cursorPath;
+    private continuityPath;
+}
+export declare function observedConversationStoreForAgent(agentId: string): ObservedConversationStore;
+//# sourceMappingURL=observed-conversation.store.d.ts.map

package/dist/server/storage/schema/observed-conversation.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observed-conversation.store.d.ts","sourceRoot":"","sources":["../../../../server/storage/schema/observed-conversation.store.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,kEAAkE;AAClE,eAAO,MAAM,mCAAmC,OAAQ,CAAC;AAEzD,8EAA8E;AAC9E,eAAO,MAAM,kCAAkC,IAAI,CAAC;AAEpD,2EAA2E;AAC3E,eAAO,MAAM,4BAA4B;;;;iBAIvC,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;iBAmBxC,CAAC;AAEL,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB;;;;;;iBAMlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B;;;;;;iBAMzC,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF,MAAM,MAAM,sBAAsB,GAC9B;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACvC;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEN,MAAM,MAAM,qBAAqB,GAC7B;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC,sBAAsB,EAAE;QAAE,MAAM,EAAE,SAAS,CAAA;KAAE,CAAC,CAAA;CAAE,GAClF;IACE,QAAQ,EAAE,KAAK,CAAC;IAChB,MAAM,EAAE,cAAc,GAAG,YAAY,GAAG,aAAa,CAAC;IACtD,MAAM,EAAE,sBAAsB,CAAC;IAC/B,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEN,kFAAkF;AAClF,eAAO,MAAM,2BAA2B;;;;;;;;;;;iBAQtC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,MAAM,WAAW,wBAAwB;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,sBAAsB,EAAE,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,yBAAyB,GACjC;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,yBAAyB,CAAA;CAAE,GACpD;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,KAAK,CAAC,EAAE,yBAAyB,CAAA;CAAE,CAAC;AAEhF,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,2EAA2E;AAC3E,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,GAAG,SAAS,CAKrB;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,CAUT;AAED,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,wBAAwB,GAC/B,sBAAsB,CAcxB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,yBAAyB,EAAE,EACnC,SAAS,EAAE,MAAM,GAChB,iBAAiB,CAcnB;AAED,MAAM,WAAW,gCAAgC;IAC/C,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,yBAAyB;IAElC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,gCAAqC;IAGjE;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAyF5E,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IAMzE;;;OAGG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IAY7E,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GACtD,OAAO,CAAC,yBAAyB,EAAE,CAAC;IAWjC,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,EAAE,CAAC;IAOhF,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAKnE;;;;;;;;;OASG;IACG,aAAa,CAAC,KAAK,EAAE;QACzB,QAAQ,EAAE,qBAAqB,CAAC;QAChC,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,sBAAsB,CAAC,EAAE,MAAM,CAAC;QAChC,oBAAoB,EAAE,MAAM,CAAC;QAC7B,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAgE1B,aAAa,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAQ/C,YAAY,CAAC,KAAK,EAAE;QACxB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAalC,mFAAmF;YACrE,gBAAgB;IAgB9B,8EAA8E;IACxE,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhE,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,UAAU;IAclB,OAAO,CAAC,WAAW;IAYnB,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,cAAc;CAKvB;AAUD,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,MAAM,GAAG,yBAAyB,CAE5F"}