@animalabs/agent-framework 0.10.0 → 0.11.0

package/src/modules/discord/index.ts

@@ -754,7 +754,7 @@ export class DiscordModule implements Module {
     });
 
     // Build a map of stored message external IDs -> internal data
-    const storedMessageMap = new Map<string, { internalId: string; content: string }>();
+    const storedMessageMap = new Map<string, { internalId: string; content: string; sourceTimestamp?: number }>();
     for (const msg of storedMessages) {
       const external = msg.metadata?.external as { id?: string } | undefined;
       if (external?.id) {
@@ -766,6 +766,9 @@ export class DiscordModule implements Module {
         storedMessageMap.set(external.id, {
           internalId: msg.id,
           content: textContent,
+          sourceTimestamp: typeof msg.metadata?.timestamp === 'number'
+            ? msg.metadata.timestamp
+            : undefined,
         });
       }
     }
@@ -774,8 +777,10 @@ export class DiscordModule implements Module {
     let editedMessages = 0;
     let deletedMessages = 0;
 
-    // Process Discord messages - check for new/edited
-    for (const discordMsg of discordMessages) {
+    // Discord history is newest-first, while addMessage appends to the stored
+    // conversation. Process oldest-first so missed messages retain chronology.
+    const chronologicalMessages = [...discordMessages].reverse();
+    for (const discordMsg of chronologicalMessages) {
       const stored = storedMessageMap.get(discordMsg.id);
       
       if (!stored) {
@@ -810,10 +815,23 @@ export class DiscordModule implements Module {
       }
     }
 
-    // Check for deletes - messages we have that Discord doesn't
-    // Only consider messages within the scrollback window (recent ones)
+    // Check for deletes only inside the history we actually fetched. A short
+    // response covers complete available history; a full page has an older
+    // boundary whose tied millisecond must be preserved.
+    const fetchedCompleteHistory = discordMessages.length < scrollback;
+    const oldestFetchedTimestamp = discordMessages.length > 0
+      ? Math.min(...discordMessages.map((msg) => msg.timestamp.getTime()))
+      : undefined;
     for (const [externalId, stored] of storedMessageMap) {
-      if (!discordMessageMap.has(externalId)) {
+      const isInsideFetchedWindow = fetchedCompleteHistory || (
+        stored.sourceTimestamp !== undefined &&
+        oldestFetchedTimestamp !== undefined &&
+        // Discord timestamps are millisecond-precise, so an older message just
+        // beyond the page can tie the oldest fetched timestamp. Preserve ties
+        // rather than guessing that an unseen boundary message was deleted.
+        stored.sourceTimestamp > oldestFetchedTimestamp
+      );
+      if (isInsideFetchedWindow && !discordMessageMap.has(externalId)) {
         // Message exists in our store but not in Discord - it was deleted
         // Note: This only catches deletes within the scrollback window
         this.ctx.removeMessage(stored.internalId);

package/src/modules/workspace/index.ts

@@ -1134,10 +1134,12 @@ export class WorkspaceModule implements Module {
       throw new Error(`Unknown mount: "${mountName}". Available: ${[...this.mounts.keys()].join(', ')}`);
     }
 
-    // Path traversal guard (CWE-22): ensure resolved path stays within mount
+    // Path traversal guard (CWE-22): ensure resolved path stays within mount.
+    // Containment must compare with the PLATFORM separator (isContainedPath):
+    // resolve() emits backslashes on Windows, so a '/'-suffixed root never
+    // prefix-matches there and every in-mount path was rejected as traversal.
     const resolved = resolve(mount.config.path, relativePath);
-    const mountRoot = mount.config.path.endsWith('/') ? mount.config.path : mount.config.path + '/';
-    if (resolved !== mount.config.path && !resolved.startsWith(mountRoot)) {
+    if (!isContainedPath(mount.config.path, resolved)) {
       throw new Error(`Path traversal detected: "${path}" resolves outside mount "${mountName}"`);
     }
 

package/src/modules/workspace/sync.ts

@@ -8,7 +8,7 @@
 
 import { createHash } from 'node:crypto';
 import { readFile, writeFile, mkdir, readdir, stat, access } from 'node:fs/promises';
-import { join, dirname, relative, resolve } from 'node:path';
+import { join, dirname, relative, resolve, sep } from 'node:path';
 import type { JsStore, JsTreeEntry } from '@animalabs/chronicle';
 import type { MountState } from './types.js';
 
@@ -19,8 +19,11 @@ export const DEFAULT_MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB
  * Returns the absolute path, or null if the path is outside the mount.
  */
 function safePath(mountPath: string, relativePath: string): string | null {
+  // Compare with the PLATFORM separator: resolve() emits backslashes on
+  // Windows, so a '/'-suffixed root never prefix-matches there and every
+  // in-mount path was reported as outside the mount.
   const resolved = resolve(mountPath, relativePath);
-  const root = mountPath.endsWith('/') ? mountPath : mountPath + '/';
+  const root = mountPath.endsWith(sep) ? mountPath : mountPath + sep;
   if (resolved !== mountPath && !resolved.startsWith(root)) {
     return null;
   }
@@ -299,7 +302,10 @@ async function walkDirectory(
       if (results.length >= maxFiles) break;
 
       const fullPath = join(dir, entry.name);
-      const relativePath = relative(basePath, fullPath);
+      // Logical workspace paths are '/'-separated everywhere (mount-prefixed
+      // paths, chronicle tree paths); node's relative() emits backslashes on
+      // Windows, so normalize. No-op on POSIX (sep === '/').
+      const relativePath = relative(basePath, fullPath).split(sep).join('/');
 
       // Check ignore patterns (simple glob matching)
       if (shouldIgnore(relativePath, entry.name, ignorePatterns)) continue;

package/src/modules/workspace/watcher.ts

@@ -7,7 +7,7 @@
 
 import { watch, type FSWatcher } from 'chokidar';
 import { mkdirSync, statSync } from 'node:fs';
-import { basename } from 'node:path';
+import { basename, sep } from 'node:path';
 import { type MountConfig } from './types.js';
 
 export type FsOp = 'created' | 'modified' | 'deleted';
@@ -363,20 +363,23 @@ export class MountWatcher {
   }
 
   private toRelative(absolutePath: string): string | null {
-    const base = this.config.path.endsWith('/')
+    // Chokidar hands back platform-separated absolute paths; compare with
+    // the platform separator and normalize the result to the '/'-separated
+    // logical form the rest of the workspace uses. No-op on POSIX.
+    const base = this.config.path.endsWith(sep)
       ? this.config.path
-      : this.config.path + '/';
+      : this.config.path + sep;
     if (absolutePath.startsWith(base)) {
-      return absolutePath.slice(base.length);
+      return absolutePath.slice(base.length).split(sep).join('/');
     }
     return null;
   }
 
   private isRootPath(absolutePath: string): boolean {
-    const root = this.config.path.endsWith('/')
+    const root = this.config.path.endsWith(sep)
       ? this.config.path.slice(0, -1)
       : this.config.path;
-    const candidate = absolutePath.endsWith('/')
+    const candidate = absolutePath.endsWith(sep)
       ? absolutePath.slice(0, -1)
       : absolutePath;
     return candidate === root;

package/src/queue.ts

@@ -22,8 +22,14 @@ export class ProcessQueueImpl implements ProcessQueue {
     if (waiter) {
       waiter(event);
     } else if (event.type === 'external-message') {
-      // User input jumps to front so it's processed before queued internal events
-      this.queue.unshift(event);
+      // User input stays ahead of queued internal work, but joins the end of
+      // the external-message lane so rapid messages retain arrival order.
+      const firstInternal = this.queue.findIndex((queued) => queued.type !== 'external-message');
+      if (firstInternal === -1) {
+        this.queue.push(event);
+      } else {
+        this.queue.splice(firstInternal, 0, event);
+      }
     } else {
       this.queue.push(event);
     }

package/src/types/agent.ts

@@ -180,8 +180,10 @@ export interface AgentConfig {
    * - 'hybrid': unprefixed prose keeps locus routing; `>>>destination` routes
    *   that publication envelope through the same authorized resolver.
    *   See docs/hybrid-prose-routing.md.
+   * - 'disabled': generated prose is never published. Only explicit tools may
+   *   send externally; prose remains in Chronicle with a private suppression receipt.
    */
-  proseRouting?: 'locus' | 'explicit' | 'hybrid';
+  proseRouting?: 'locus' | 'explicit' | 'hybrid' | 'disabled';
 }
 
 /** The intentionally small set of agent settings that may change in-process. */

package/src/types/trace.ts

@@ -340,6 +340,19 @@ export type TraceEvent =
       textLen: number;
     })
 
+  // Admin puppet: an operator executed a tool AS an agent and stored the
+  // tool_use + tool_result pair in that agent's window (Framework.
+  // puppetToolCall). Provenance lives HERE and in the host log — the stored
+  // messages deliberately byte-match a model-initiated call.
+  | (TraceEventBase & {
+      type: 'puppet:tool-call';
+      agentName: string;
+      toolName: string;
+      toolUseId: string;
+      isError: boolean;
+      durationMs: number;
+    })
+
   // MCPL server connection lifecycle (spawn / handshake / reconnect health).
   // Previously these outcomes were visible only on the host process's own
   // stderr, so a server that lost the boot handshake race just went missing.

package/dist/test/fixtures/awareness-barrier-mcpl-server.mjs

@@ -1,276 +0,0 @@
-import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
-
-const statusPath = process.env.STATUS_PATH;
-const ledgerPath = process.env.LEDGER_PATH;
-const releasePath = process.env.RELEASE_PATH;
-const crashPath = process.env.CRASH_PATH;
-const generationPath = process.env.GENERATION_PATH;
-const listChangePath = process.env.LIST_CHANGE_PATH;
-const failReaction = process.env.FAIL_REACTION === '1';
-const permanentReaction = process.env.PERMANENT_REACTION === '1';
-const failInitialGeneration = process.env.FAIL_INITIAL_GENERATION === '1';
-const nestedListChangeGeneration = Number(process.env.NESTED_LIST_CHANGE_GENERATION ?? 0);
-const dataMethod = process.env.DATA_METHOD ?? 'push/event';
-const serverId = process.env.SERVER_ID ?? 'discord';
-const arrivalPath = process.env.ARRIVAL_PATH;
-const waitForArrivalPath = process.env.WAIT_FOR_ARRIVAL_PATH;
-
-let generation = 1;
-if (generationPath) {
-  try {
-    generation = Number(readFileSync(generationPath, 'utf8')) + 1;
-  } catch {
-    // First process for this test.
-  }
-  writeFileSync(generationPath, String(generation));
-}
-
-const log = (event, extra = {}) => {
-  if (!statusPath) return;
-  appendFileSync(statusPath, JSON.stringify({ event, generation, serverId, ...extra }) + '\n');
-};
-const send = (message) => process.stdout.write(JSON.stringify(message) + '\n');
-const request = (id, method, params) => send({ jsonrpc: '2.0', id, method, params });
-const reply = (id, result) => send({ jsonrpc: '2.0', id, result });
-const channel = (suffix) => ({
-  id: `${serverId}:guild:${suffix}`,
-  type: serverId,
-  label: suffix,
-  direction: 'bidirectional',
-});
-
-if (failInitialGeneration && generation === 1) {
-  log('initial-connect-failure');
-  process.exit(9);
-}
-
-let initialized = false;
-let registered = false;
-let registrationReceived = false;
-let pendingToolRequest = null;
-let reactionQueued = false;
-let pendingControl = false;
-let listChangeTriggered = false;
-let reactionOrdinal = 0;
-let buf = '';
-
-function ledgerDeliveryStatus() {
-  if (!ledgerPath) return 'missing';
-  try {
-    const document = JSON.parse(readFileSync(ledgerPath, 'utf8'));
-    return document.batches?.[0]?.refs?.[0]?.deliveryStatus ?? 'missing';
-  } catch {
-    return 'unreadable';
-  }
-}
-
-function maybeReplyToReaction() {
-  if (!pendingToolRequest || pendingControl || failReaction) return;
-  if (releasePath) {
-    if (!existsSync(releasePath)) return;
-    const releaseValue = readFileSync(releasePath, 'utf8').trim();
-    const releaseOrdinal = Number(releaseValue);
-    if (Number.isFinite(releaseOrdinal) && releaseOrdinal < pendingToolRequest.ordinal) return;
-  }
-  const requestId = pendingToolRequest.id;
-  pendingToolRequest = null;
-  log('reaction-response');
-  reply(requestId, permanentReaction
-    ? { isError: true, content: [{ type: 'text', text: 'Unknown Message' }] }
-    : { content: [{ type: 'text', text: 'Reaction applied' }] });
-}
-
-function serviceReaction(message) {
-  if (waitForArrivalPath && !existsSync(waitForArrivalPath)) {
-    pendingToolRequest = message;
-    return;
-  }
-  if (!registered) {
-    pendingToolRequest = message;
-    if (!reactionQueued) {
-      reactionQueued = true;
-      log('reaction-queued-before-registration');
-    }
-    return;
-  }
-  reactionOrdinal++;
-  pendingToolRequest = { ...message, ordinal: reactionOrdinal };
-  pendingControl = true;
-  log('reaction-call', { name: message.params?.name, ordinal: reactionOrdinal });
-  request(201, 'channels/register', { channels: [channel('control-during-barrier')] });
-  if (
-    nestedListChangeGeneration === generation
-    && reactionOrdinal === 1
-    && !listChangeTriggered
-  ) {
-    listChangeTriggered = true;
-    log('tools-list-changed-notification');
-    send({ jsonrpc: '2.0', method: 'notifications/tools/list_changed', params: {} });
-    sendDataRequest(302, 'list-change');
-  }
-}
-
-function maybeFinishRegistration() {
-  if (!registrationReceived || registered) return;
-  if (pendingToolRequest && waitForArrivalPath && !existsSync(waitForArrivalPath)) return;
-  if (pendingToolRequest && !reactionQueued) serviceReaction(pendingToolRequest);
-  registered = true;
-  log('registration-response');
-  const queued = pendingToolRequest;
-  pendingToolRequest = null;
-  if (queued) serviceReaction(queued);
-}
-
-function sendDataRequest(id, phase) {
-  let params;
-  if (dataMethod === 'inference/request') {
-    params = {
-      featureSet: 'chat',
-      messages: [{ role: 'user', content: `must wait for ${phase} awareness` }],
-    };
-  } else if (dataMethod === 'channels/incoming') {
-    params = {
-      messages: [{
-        channelId: `${serverId}:guild:startup`,
-        messageId: `${serverId}-${phase}-incoming-${generation}`,
-        author: { id: 'human', name: 'Human' },
-        timestamp: new Date().toISOString(),
-        content: [{ type: 'text', text: `must wait for ${phase} awareness` }],
-      }],
-    };
-  } else if (dataMethod === 'host/command') {
-    params = { command: 'barrier-probe', agentName: 'assistant' };
-  } else {
-    params = {
-      featureSet: 'chat',
-      eventId: `${serverId}-${phase}-push-${generation}`,
-      timestamp: new Date().toISOString(),
-      payload: { content: [{ type: 'text', text: `must wait for ${phase} awareness` }] },
-    };
-  }
-  log('data-request-sent', { method: dataMethod, phase });
-  if (arrivalPath) writeFileSync(arrivalPath, `${serverId}:${dataMethod}:${phase}`);
-  request(id, dataMethod, params);
-}
-
-function beginServerTraffic() {
-  if (initialized) return;
-  initialized = true;
-  log('initialized');
-  request(200, 'channels/register', { channels: [channel('startup')] });
-  // The reconnect generation carries an inference-bearing event in the same
-  // registration window. Initial-start tests use generation 1 as well.
-  sendDataRequest(202, 'startup');
-}
-
-function handle(message) {
-  if (message.method === 'initialize') {
-    reply(message.id, {
-      capabilities: {
-        experimental: {
-          mcpl: {
-            version: '0.5',
-            // §5.4/§6.2: the grant is computed from this advertisement, and
-            // admission denies what it cannot contain. This fixture SENDS
-            // channels/register, channels/incoming and inference/request, so
-            // it must advertise them — with only pushEvents declared, the
-            // 0.5 host correctly rejected the released data requests
-            // (accepted:false), which is exactly what PR #79's ubuntu CI
-            // caught on the inference/request + channels/incoming matrix.
-            pushEvents: true,
-            inferenceRequest: true,
-            channels: { register: true, incoming: true },
-            featureSets: {
-              chat: { description: 'chat', uses: ['pushEvents'] },
-            },
-          },
-        },
-      },
-    });
-    return;
-  }
-  if (message.method === 'featureSets/update') {
-    // MCPL 0.5 (§5.3/§6.7): the host sends initial policy as a Request and
-    // activates the grant only on this degradation receipt. Without it the
-    // host times out (15s), the grant stays empty, and every push/channel
-    // in these tests is rejected fail-closed.
-    if (message.id !== undefined && message.id !== null) {
-      reply(message.id, { accepted: true });
-    }
-    return;
-  }
-  if (message.method === 'notifications/initialized') {
-    beginServerTraffic();
-    return;
-  }
-  if (message.method === 'tools/list') {
-    log('tools-list');
-    reply(message.id, {
-      tools: [
-        { name: 'add_reaction', description: 'add', inputSchema: { type: 'object' } },
-        { name: 'remove_reaction', description: 'remove', inputSchema: { type: 'object' } },
-      ],
-    });
-    return;
-  }
-  if (message.method === 'tools/call') {
-    serviceReaction(message);
-    return;
-  }
-  if (message.id === 200) {
-    registrationReceived = true;
-    maybeFinishRegistration();
-    return;
-  }
-  if (message.id === 201) {
-    pendingControl = false;
-    log('control-response-during-barrier');
-    maybeReplyToReaction();
-    return;
-  }
-  if (message.id === 202 || message.id === 302) {
-    const event = message.id === 202 ? 'push-response' : 'list-change-push-response';
-    const accepted = message.result?.accepted
-      ?? message.result?.results?.[0]?.accepted
-      ?? (message.error == null);
-    log(event, {
-      method: dataMethod,
-      accepted,
-      ledgerStatus: ledgerDeliveryStatus(),
-    });
-  }
-}
-
-process.stdin.on('data', (chunk) => {
-  buf += chunk.toString('utf8');
-  let newline;
-  while ((newline = buf.indexOf('\n')) >= 0) {
-    const line = buf.slice(0, newline);
-    buf = buf.slice(newline + 1);
-    if (!line.trim()) continue;
-    try {
-      handle(JSON.parse(line));
-    } catch (error) {
-      log('server-error', { message: error instanceof Error ? error.message : String(error) });
-    }
-  }
-});
-
-const timer = setInterval(() => {
-  if (pendingToolRequest && !registered && waitForArrivalPath && existsSync(waitForArrivalPath)) {
-    serviceReaction(pendingToolRequest);
-    maybeFinishRegistration();
-  }
-  maybeReplyToReaction();
-  if (listChangePath && existsSync(listChangePath) && !listChangeTriggered) {
-    listChangeTriggered = true;
-    log('tools-list-changed-notification');
-    send({ jsonrpc: '2.0', method: 'notifications/tools/list_changed', params: {} });
-    sendDataRequest(302, 'list-change');
-  }
-  if (crashPath && existsSync(crashPath) && generation === 1) {
-    log('crashing');
-    process.exit(7);
-  }
-}, 5);
-timer.unref();

package/dist/test/fixtures/flaky-mcpl-server.mjs

@@ -1,41 +0,0 @@
-// Minimal MCP server for reconnect tests.
-//
-// Availability is controlled by a flag file passed as argv[2]: when the file
-// does not exist the process exits(1) immediately (simulating a server that
-// loses the boot race); when it exists the process answers the MCP
-// `initialize` handshake and stays alive.
-//
-// Receiving a `tools/list` request makes it exit(7) — tests use this as a
-// remote-controlled crash to exercise the unexpected-exit reconnect path.
-import { existsSync } from 'node:fs';
-import { createInterface } from 'node:readline';
-
-const flagFile = process.argv[2];
-if (flagFile && !existsSync(flagFile)) process.exit(1);
-
-const rl = createInterface({ input: process.stdin });
-rl.on('line', (line) => {
-  let msg;
-  try {
-    msg = JSON.parse(line);
-  } catch {
-    return;
-  }
-  if (msg.method === 'initialize') {
-    process.stdout.write(
-      JSON.stringify({
-        jsonrpc: '2.0',
-        id: msg.id,
-        result: {
-          protocolVersion: '2024-11-05',
-          capabilities: {
-            experimental: { mcpl: { version: '0.5', pushEvents: true } },
-          },
-          serverInfo: { name: 'flaky-mcpl-server', version: '0.0.0' },
-        },
-      }) + '\n',
-    );
-  } else if (msg.method === 'tools/list') {
-    process.exit(7);
-  }
-});