@animalabs/agent-framework 0.11.0 → 0.13.0

package/src/tune-out/tools.ts

@@ -0,0 +1,129 @@
+/**
+ * The subconscious's tool surface (issue #77).
+ *
+ * Deliberately small and channel-scoped: the subconscious observes the
+ * merged timeline, judges wakes, and reports — it is not a general agent.
+ * Names and results carry no credential/config vocabulary; everything it
+ * says to the resident is its own text (never host-templated), delivered
+ * under its own participant name. Prose is never auto-routed
+ * (proseRouting: 'explicit' on its AgentConfig): speaking into a channel
+ * happens only through speak_in_channel, so a timer-triggered turn can
+ * never leak bare prose to the default locus.
+ */
+
+import type { ToolDefinition } from '../types/index.js';
+
+export const SUBCONSCIOUS_TOOL_NAMES = [
+  'deliver_summary',
+  'cancel_tuneout',
+  'note_disposition',
+  'speak_in_channel',
+] as const;
+
+export type SubconsciousToolName = (typeof SUBCONSCIOUS_TOOL_NAMES)[number];
+
+export const SUBCONSCIOUS_TOOLS: ToolDefinition[] = [
+  {
+    name: 'deliver_summary',
+    description:
+      'Deliver a summary into the resident\'s context, in your own voice, ' +
+      'addressed to them (second person). Use at cadence when the diverted ' +
+      'traffic merits it; staying silent is always allowed — an empty ' +
+      'period needs no report.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: {
+          type: 'string',
+          description: 'The summary, verbatim as the resident will read it.',
+        },
+        channelId: {
+          type: 'string',
+          description: 'The tuned-out channel this summary covers.',
+        },
+      },
+      required: ['text', 'channelId'],
+    },
+  },
+  {
+    name: 'cancel_tuneout',
+    description:
+      'End the tune-out on a channel now — use when something needs the ' +
+      'resident\'s full attention. The diverted backlog is delivered to ' +
+      'them (capped), and normal attention resumes. Add your own note in ' +
+      '`text`; it arrives alongside the backlog, in your voice.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        channelId: { type: 'string' },
+        text: {
+          type: 'string',
+          description: 'Your accompanying note to the resident (optional).',
+        },
+      },
+      required: ['channelId'],
+    },
+  },
+  {
+    name: 'note_disposition',
+    description:
+      'Record a standing disposition for yourself — a durable note that ' +
+      'shapes how you treat future traffic ("antra\'s pings always ' +
+      'escalate", "ignore release-bot"). Replaces any previous note under ' +
+      'the same key.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        key: { type: 'string', description: 'Short stable identifier.' },
+        text: {
+          type: 'string',
+          description: 'The disposition. Empty string deletes the key.',
+        },
+      },
+      required: ['key', 'text'],
+    },
+  },
+  {
+    name: 'speak_in_channel',
+    description:
+      'Post a message into a tuned-out channel, clearly as yourself (not ' +
+      'as the resident). Use sparingly — e.g. to tell someone the resident ' +
+      'is tuned out and when to expect them. Disabled unless the resident\'s ' +
+      'configuration allows it.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        channelId: { type: 'string' },
+        text: { type: 'string' },
+      },
+      required: ['channelId', 'text'],
+    },
+  },
+];
+
+/**
+ * Configuration for the subconscious resident (FrameworkConfig.subconscious).
+ */
+export interface SubconsciousConfig {
+  /** Master switch. */
+  enabled: boolean;
+  /**
+   * Registry + participant name. Default 'Subconscious' — following the
+   * Context Manager precedent: a title-case functional voice, not an
+   * agent-prefixed identifier.
+   */
+  name?: string;
+  /** Model id; defaults to the primary agent's (same-model side-process). */
+  model?: string;
+  /**
+   * The voice/criteria mode block — recipe-side and co-authored with the
+   * resident (it is an aspect of their attention). Report-shaped, second
+   * person toward the resident. Canary before fleet use (issue #77).
+   */
+  systemPrompt: string;
+  /** Allow speak_in_channel. Default false until the voice block has
+   *  passed its canary round. */
+  allowChannelSpeech?: boolean;
+  /** WindowedPassthroughStrategy re-anchor fraction (default 0.5). */
+  reAnchorFraction?: number;
+}

package/src/types/agent.ts

@@ -184,6 +184,14 @@ export interface AgentConfig {
    *   send externally; prose remains in Chronicle with a private suppression receipt.
    */
   proseRouting?: 'locus' | 'explicit' | 'hybrid' | 'disabled';
+
+  /**
+   * Fail-closed containment for a text response whose entire visible prose is
+   * an invocation-shaped wrapper naming a tool registered on that exact turn.
+   * The wrapper is neither executed nor stored as assistant continuity; a
+   * content-free system receipt is stored instead. Default false.
+   */
+  toolWrapperProseGuard?: boolean;
 }
 
 /** The intentionally small set of agent settings that may change in-process. */
@@ -310,4 +318,12 @@ export interface InferenceRequest {
    * not capture the agent's voice just by being newest.
    */
   addressed?: boolean;
+  /**
+   * Who spoke the message that triggered this inference, as an adapter-
+   * namespaced opaque id (`<serverId>:user:<authorId>`) — never a display
+   * name. Undefined for wakes without an author (heartbeat, timers, module
+   * events). Read by the host to stamp gateway telemetry (x-gate-counterparty)
+   * so a household ledger can say who woke whom; carries no content.
+   */
+  counterparty?: string;
 }

package/src/types/framework.ts

@@ -71,6 +71,13 @@ export interface CodeExecutionConfig {
 }
 
 export interface FrameworkConfig {
+  /**
+   * The subconscious resident (issue #77): a persistent side-agent that
+   * receives diverted traffic from tuned-out channels and reports to the
+   * resident in its own voice. See src/tune-out/tools.ts.
+   */
+  subconscious?: import('../tune-out/tools.js').SubconsciousConfig;
+
   /**
    * IANA zone used only when rendering wall-clock times for the agent.
    * Stored/protocol timestamps remain epoch/UTC. Defaults to AGENT_TIMEZONE,

package/src/usage-accounting.ts

@@ -0,0 +1,8 @@
+/** Convert a cumulative usage counter into the contribution of this call.
+ * A counter reset (provider/stream implementation change) is treated as an
+ * already-per-call sample rather than producing a negative value. */
+export function cumulativeDelta(current: number, previous: number): number {
+  if (!Number.isFinite(current) || current < 0) return 0;
+  if (!Number.isFinite(previous) || previous < 0 || current < previous) return current;
+  return current - previous;
+}