@pellux/goodvibes-agent 1.5.1 → 1.5.3

package/src/agent/channel-profile-routing.ts

@@ -0,0 +1,330 @@
+/**
+ * channel-profile-routing.ts
+ *
+ * Agent-side channel-to-profile routing scaffold.
+ *
+ * Assigns a channel (surface kind, optional route id) to an active GoodVibes
+ * profile so that incoming channel interactions can be routed to the correct
+ * agent persona/profile context.
+ *
+ * Persistence: JSON file at {agentRoot}/channels/profile-routes.json via
+ * ShellPathService. Assignments are agent-local and survive sessions.
+ *
+ * SEAM — Daemon contract needed for full runtime routing:
+ *
+ *   Daemon method:  channels.routing.assign
+ *   Input:          { channelId: string; profileId: string; routeId?: string }
+ *   Output:         { assignmentId: string; channelId: string; profileId: string }
+ *
+ *   Until that method is published, this module persists assignments locally.
+ *   The `daemonMethodNeeded` field on each assignment makes the gap machine-
+ *   readable so tooling can detect and surface it.
+ *
+ *   When the daemon method ships:
+ *   1. Add an adapter that calls operator.invoke('channels.routing.assign', ...)
+ *   2. Mirror the local store for offline fallback
+ *   3. Remove the `daemonSyncState: 'local_only'` flag from existing records
+ */
+
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { ShellPathService } from '@/runtime/index.ts';
+import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Represents a channel-to-profile assignment.
+ *
+ * `surfaceKind` maps to the existing ChannelDeliverySurfaceKind values
+ * (slack, discord, telegram, etc.) plus 'any' as a wildcard.
+ */
+export interface ChannelProfileRoute {
+  readonly version: 1;
+  readonly id: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  /** The channel surface kind (e.g. 'slack', 'discord', 'telegram'). Use 'any' as wildcard. */
+  readonly surfaceKind: string;
+  /** Optional route id to narrow beyond surface kind. */
+  readonly routeId?: string;
+  /** The profile id to route this channel to. */
+  readonly profileId: string;
+  /** Optional human-readable label. */
+  readonly label?: string;
+  /**
+   * Indicates this assignment lives only in the local agent store.
+   * Remains 'local_only' until daemon publishes channels.routing.assign.
+   */
+  readonly daemonSyncState: 'local_only';
+  /**
+   * SEAM: the daemon operator method needed for runtime-aware routing.
+   * Remove this field once the contract is published and synced.
+   */
+  readonly daemonMethodNeeded: 'channels.routing.assign';
+}
+
+export interface ChannelProfileRouteSnapshot {
+  readonly path: string;
+  readonly exists: boolean;
+  readonly routes: readonly ChannelProfileRoute[];
+  readonly parseError?: string;
+}
+
+export interface ChannelProfileRouteAssignResult {
+  readonly route: ChannelProfileRoute;
+  readonly path: string;
+  readonly created: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Internal file model
+// ---------------------------------------------------------------------------
+
+interface ChannelProfileRouteFile {
+  readonly version: 1;
+  readonly routes: readonly ChannelProfileRoute[];
+}
+
+type ShellPaths = Pick<ShellPathService, 'resolveUserPath'>;
+
+const ROUTE_VERSION = 1 as const;
+const ROUTE_FILE_VERSION = 1 as const;
+const ROUTE_LIMIT = 500;
+
+// ---------------------------------------------------------------------------
+// Path
+// ---------------------------------------------------------------------------
+
+export function channelProfileRouteFilePath(shellPaths: ShellPaths): string {
+  return shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'channels', 'profile-routes.json');
+}
+
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readOptString(value: unknown): string | undefined {
+  const s = readString(value);
+  return s || undefined;
+}
+
+function parseRoute(value: unknown): ChannelProfileRoute | null {
+  if (!isRecord(value) || value.version !== ROUTE_VERSION) return null;
+  const id = readString(value.id);
+  const createdAt = readString(value.createdAt);
+  const updatedAt = readString(value.updatedAt);
+  const surfaceKind = readString(value.surfaceKind);
+  const profileId = readString(value.profileId);
+  if (!id || !createdAt || !updatedAt || !surfaceKind || !profileId) return null;
+  if (Number.isNaN(Date.parse(createdAt)) || Number.isNaN(Date.parse(updatedAt))) return null;
+  return {
+    version: ROUTE_VERSION,
+    id,
+    createdAt,
+    updatedAt,
+    surfaceKind,
+    profileId,
+    ...( readOptString(value.routeId) ? { routeId: readOptString(value.routeId) } : {}),
+    ...( readOptString(value.label) ? { label: readOptString(value.label) } : {}),
+    daemonSyncState: 'local_only',
+    daemonMethodNeeded: 'channels.routing.assign',
+  };
+}
+
+function parseRouteFile(raw: unknown): ChannelProfileRouteFile {
+  if (!isRecord(raw)) return { version: ROUTE_FILE_VERSION, routes: [] };
+  const routes = Array.isArray(raw.routes)
+    ? raw.routes.map(parseRoute).filter((r): r is ChannelProfileRoute => r !== null)
+    : [];
+  return { version: ROUTE_FILE_VERSION, routes };
+}
+
+// ---------------------------------------------------------------------------
+// Read / write
+// ---------------------------------------------------------------------------
+
+export function readChannelProfileRoutes(shellPaths: ShellPaths): ChannelProfileRouteSnapshot {
+  const path = channelProfileRouteFilePath(shellPaths);
+  if (!existsSync(path)) return { path, exists: false, routes: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as unknown;
+    return { path, exists: true, routes: parseRouteFile(parsed).routes };
+  } catch (error) {
+    return {
+      path,
+      exists: true,
+      routes: [],
+      parseError: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function writeRoutes(path: string, routes: readonly ChannelProfileRoute[]): void {
+  const file: ChannelProfileRouteFile = {
+    version: ROUTE_FILE_VERSION,
+    routes: routes.slice(0, ROUTE_LIMIT),
+  };
+  mkdirSync(dirname(path), { recursive: true });
+  const tempPath = `${path}.tmp`;
+  writeFileSync(tempPath, `${JSON.stringify(file, null, 2)}\n`, 'utf-8');
+  renameSync(tempPath, path);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Assign a channel (identified by surfaceKind + optional routeId) to a profile.
+ *
+ * If an assignment for the same (surfaceKind, routeId) pair already exists,
+ * it is updated in-place. Otherwise a new assignment is created.
+ *
+ * Returns the assignment record and whether it was newly created.
+ *
+ * SEAM: when daemon publishes `channels.routing.assign`, add a call here and
+ * set `daemonSyncState` based on the daemon response.
+ */
+export function assignChannelToProfile(
+  shellPaths: ShellPaths,
+  input: {
+    readonly surfaceKind: string;
+    readonly routeId?: string;
+    readonly profileId: string;
+    readonly label?: string;
+  },
+): ChannelProfileRouteAssignResult {
+  const surfaceKind = input.surfaceKind.trim();
+  const profileId = input.profileId.trim();
+  if (!surfaceKind) throw new Error('surfaceKind is required for channel-to-profile assignment.');
+  if (!profileId) throw new Error('profileId is required for channel-to-profile assignment.');
+
+  const snapshot = readChannelProfileRoutes(shellPaths);
+  const path = channelProfileRouteFilePath(shellPaths);
+  const now = new Date().toISOString();
+
+  // Find existing assignment for the same (surfaceKind, routeId) pair
+  const routeId = input.routeId?.trim() || undefined;
+  const existingIndex = snapshot.routes.findIndex(
+    (r) => r.surfaceKind === surfaceKind && r.routeId === routeId,
+  );
+  const existing = existingIndex >= 0 ? snapshot.routes[existingIndex] : null;
+  const created = !existing;
+
+  const route: ChannelProfileRoute = {
+    version: ROUTE_VERSION,
+    id: existing?.id ?? `cpr-${new Date().toISOString().replace(/[^0-9]/g, '').slice(0, 14)}-${randomUUID().slice(0, 8)}`,
+    createdAt: existing?.createdAt ?? now,
+    updatedAt: now,
+    surfaceKind,
+    profileId,
+    ...(routeId ? { routeId } : {}),
+    ...(input.label?.trim() ? { label: input.label.trim() } : {}),
+    daemonSyncState: 'local_only',
+    daemonMethodNeeded: 'channels.routing.assign',
+  };
+
+  let updatedRoutes: readonly ChannelProfileRoute[];
+  if (existingIndex >= 0) {
+    updatedRoutes = snapshot.routes.map((r, i) => (i === existingIndex ? route : r));
+  } else {
+    updatedRoutes = [route, ...snapshot.routes];
+  }
+
+  writeRoutes(path, updatedRoutes);
+  return { route, path, created };
+}
+
+/** List all channel-to-profile assignments, optionally filtered by profileId. */
+export function listChannelProfileRoutes(
+  shellPaths: ShellPaths,
+  options: { readonly profileId?: string; readonly surfaceKind?: string } = {},
+): ChannelProfileRouteSnapshot {
+  const snapshot = readChannelProfileRoutes(shellPaths);
+  let routes = snapshot.routes;
+  if (options.profileId) {
+    routes = routes.filter((r) => r.profileId === options.profileId);
+  }
+  if (options.surfaceKind) {
+    routes = routes.filter((r) => r.surfaceKind === options.surfaceKind || r.surfaceKind === 'any');
+  }
+  return { ...snapshot, routes };
+}
+
+/**
+ * Get the profile id for an incoming channel message.
+ *
+ * Resolution order: exact (surfaceKind + routeId) → surface wildcard (surfaceKind only) → any wildcard.
+ * Returns null if no assignment exists.
+ */
+export function getProfileForChannel(
+  shellPaths: ShellPaths,
+  surfaceKind: string,
+  routeId?: string,
+): string | null {
+  const snapshot = readChannelProfileRoutes(shellPaths);
+  const { routes } = snapshot;
+
+  // Exact match: surfaceKind + routeId
+  if (routeId) {
+    const exact = routes.find((r) => r.surfaceKind === surfaceKind && r.routeId === routeId);
+    if (exact) return exact.profileId;
+  }
+
+  // Surface match: surfaceKind only (no routeId on the assignment)
+  const surfaceMatch = routes.find((r) => r.surfaceKind === surfaceKind && !r.routeId);
+  if (surfaceMatch) return surfaceMatch.profileId;
+
+  // Wildcard match
+  const wildcard = routes.find((r) => r.surfaceKind === 'any');
+  if (wildcard) return wildcard.profileId;
+
+  return null;
+}
+
+/** Remove a channel-to-profile assignment by id. Returns true if removed. */
+export function removeChannelProfileRoute(
+  shellPaths: ShellPaths,
+  routeId: string,
+): boolean {
+  const snapshot = readChannelProfileRoutes(shellPaths);
+  const before = snapshot.routes.length;
+  const updated = snapshot.routes.filter((r) => r.id !== routeId);
+  if (updated.length === before) return false;
+  writeRoutes(channelProfileRouteFilePath(shellPaths), updated);
+  return true;
+}
+
+/** Format the routing table for human-readable output. */
+export function formatChannelProfileRoutes(snapshot: ChannelProfileRouteSnapshot): string {
+  const lines = [
+    'Channel-to-Profile Routing',
+    `  path: ${snapshot.path}`,
+    `  total: ${snapshot.routes.length}`,
+    `  sync: local_only — daemon method needed: channels.routing.assign`,
+    `  status: ${snapshot.parseError ? 'attention' : snapshot.exists ? 'ready' : 'empty'}`,
+    ...(snapshot.parseError ? [`  parse error: ${snapshot.parseError}`] : []),
+    '',
+  ];
+  if (snapshot.routes.length === 0) {
+    lines.push('  no channel-to-profile assignments');
+  } else {
+    for (const route of snapshot.routes) {
+      const channelDesc = route.routeId ? `${route.surfaceKind}:${route.routeId}` : route.surfaceKind;
+      lines.push(`  ${route.id}  channel=${channelDesc} → profile=${route.profileId}${route.label ? ` (${route.label})` : ''}  sync=${route.daemonSyncState}`);
+    }
+  }
+  return lines.join('\n');
+}

package/src/agent/email/style-reply-lane.ts

@@ -0,0 +1,179 @@
+/**
+ * Personal Ops lane descriptor for the writing-style-matched draft-reply flow.
+ *
+ * This module defines the PersonalOpsWorkflow and PersonalOpsLiveRecord objects
+ * that surface the style-reply capability inside the existing Personal Ops
+ * 'inbox' lane.  It is integrated into buildLanes() in
+ * agent-harness-personal-ops-lanes.ts by appending the exported items to the
+ * inbox lane's workflows and liveRecords arrays.
+ *
+ * BEFORE-SEND REVIEW BOUNDARY (enforced here and in style-reply.ts)
+ * ──────────────────────────────────────────────────────────────────────
+ * The style-reply lane ONLY produces a DRAFT. Composition is local-only in
+ * nature (the live record's typed `effect` is 'read-only' — the closest value
+ * in the PersonalOpsLiveRecord.effect union — and it carries no `freshness`, so
+ * it is never counted as a provider read). Sending requires the confirmed send path
+ * (EmailService.sendMail with confirm:true, or an MCP connector action) with
+ * explicit user review and confirmation before any provider effect is executed.
+ *
+ * The confirmationRequired flag on the send follow-up route is always true.
+ * Auto-send is architecturally impossible from this module.
+ *
+ * INTEGRATION
+ * ────────────
+ * This module is consumed by src/tools/agent-harness-personal-ops-lanes.ts
+ * only (no new top-level harness mode is registered here).
+ *
+ * // INTEGRATION: if a new top-level mode 'inbox_style_reply' is desired in
+ * // agent_harness, register it in agent-harness-mode-catalog.ts (that file
+ * // is owned by another agent — leave this comment for the orchestrator).
+ */
+
+import type {
+  PersonalOpsLiveRecord,
+  PersonalOpsWorkflow,
+  PersonalOpsWorkflowStatus,
+} from '../../tools/agent-harness-personal-ops-types.ts';
+
+// ---------------------------------------------------------------------------
+// Workflow status helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Determine the workflow status for the style-reply lane.
+ *
+ * The lane is 'ready' when at least one email connector or daemon method is
+ * available (signalled by hasEmailCapability = true).  Otherwise 'needs-setup'.
+ */
+export function styleReplyWorkflowStatus(hasEmailCapability: boolean): PersonalOpsWorkflowStatus {
+  return hasEmailCapability ? 'ready' : 'needs-setup';
+}
+
+// ---------------------------------------------------------------------------
+// Workflow descriptor
+// ---------------------------------------------------------------------------
+
+/**
+ * Personal Ops workflow card for the writing-style-matched draft-reply flow.
+ *
+ * Presence in inbox lane's `workflows` array makes it discoverable via
+ * `personal_ops action:"intake" query:"draft reply in my style"` and similar.
+ */
+export function styleReplyWorkflow(hasEmailCapability: boolean): PersonalOpsWorkflow {
+  const status = styleReplyWorkflowStatus(hasEmailCapability);
+  return {
+    id: 'inbox-style-matched-draft-reply',
+    label: 'Writing-style-matched draft reply',
+    status,
+    summary:
+      'Compose a draft email reply that mirrors the user\'s own writing style '
+      + '(tone, length, greeting, sign-off) inferred from prior sent messages. '
+      + 'The draft is produced locally and NEVER auto-sent.',
+    next: status === 'ready'
+      ? 'Call personal_ops action:"read" laneId:"inbox" recordId:"inbox-style-reply-draft" '
+        + 'with the inbound message and optional key-points context. '
+        + 'Review the composed draft in the Agent transcript before sending through the confirmed send route.'
+      : 'Set up an email connector or IMAP/SMTP config (email.enabled = true) before drafting in the user\'s style.',
+    modelRoute: 'personal_ops action:"read" laneId:"inbox" recordId:"inbox-style-reply-draft" '
+      + 'fields:{inboundFrom:"...",inboundSubject:"...",inboundBodyPreview:"...",context:"key points to include"} '
+      + 'confirm:true explicitUserRequest:"draft a reply in my style"',
+    inspectRoutes: [
+      'personal_ops action:"lane" laneId:"inbox" includeParameters:true',
+      'personal_ops action:"intake" query:"draft reply in my style" includeParameters:true',
+    ],
+    prerequisites: status === 'needs-setup'
+      ? ['Configure email (email.enabled=true, IMAP+SMTP or an MCP inbox connector) before using style-matched drafts.']
+      : [
+        'The user must identify the inbound message (from, subject, bodyPreview).',
+        'Optionally supply key-points context to weave into the draft.',
+        'Review the draft in the Agent transcript before any send route.',
+      ],
+    runBoundary:
+      'Composing stays local (local-only effect). '
+      + 'Sending requires the confirmed SMTP/connector route with explicit user review of recipients and body.',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Live record descriptor
+// ---------------------------------------------------------------------------
+
+/**
+ * Live record for the inbox lane’s liveRecords array that exposes the
+ * style-reply composer as a Personal Ops read route.
+ *
+ * The `effect` is 'read-only' (the local composer performs no provider write);
+ * it carries no `freshness` so it is not counted as a provider read. Send is a
+ * separate confirmed route.
+ */
+export function styleReplyLiveRecord(hasEmailCapability: boolean): PersonalOpsLiveRecord {
+  const status = hasEmailCapability ? 'ready' : 'needs-setup';
+  return {
+    id: 'inbox-style-reply-draft',
+    label: 'Draft reply in my writing style',
+    status,
+    summary:
+      'Locally compose a draft email reply that mirrors the user\'s tone, '
+      + 'length, greeting, and sign-off. The draft is shown for review; '
+      + 'no send occurs until the user explicitly confirms through the send route.',
+    userRoute: 'Agent Workspace → Personal Ops → Inbox → Draft reply in my style',
+    modelRoute:
+      'personal_ops action:"read" laneId:"inbox" recordId:"inbox-style-reply-draft" '
+      + 'fields:{inboundFrom:"<from>",inboundSubject:"<subject>",inboundBodyPreview:"<preview>",context:"<key points>"} '
+      + 'confirm:true explicitUserRequest:"draft a reply in my style"',
+    tags: ['style-reply', 'draft', 'inbox', 'personal-ops', 'writing-style'],
+    // Note: PersonalOpsLiveRecord.effect only supports 'read-only' | 'confirmed-effect'.
+    // Style-reply composition has no provider effect, so 'read-only' is the correct value.
+    // The local-only nature is communicated via the followUpRoutes policy and reviewBoundary.
+    effect: 'read-only' as const,
+    capability: 'inbox-style-reply-draft',
+    confirmationRequired: false, // local composition; no provider effect
+    requiredFields: ['inboundFrom', 'inboundSubject'],
+    optionalFields: ['inboundBodyPreview', 'context'],
+    sampleInput: {
+      inboundFrom: 'Alice Smith <alice@example.com>',
+      inboundSubject: 'Project update',
+      inboundBodyPreview: 'Hi, just checking in on the project status...',
+      context: 'Mention the milestone is on track and you will share a detailed update by Friday.',
+    },
+    followUpRoutes: [
+      {
+        id: 'send-after-review',
+        label: 'Send reviewed draft (confirmed)',
+        effect: 'confirmed-effect',
+        modelRoute:
+          'email action:"send" to:"<recipient>" subject:"Re: <subject>" body:"<reviewed draft>" '
+          + 'confirm:true explicitUserRequest:"send this reply"',
+        requiresConfirmation: true,
+        policy:
+          'Sending requires confirm:true, explicit user review of the exact '
+          + 'recipients and body, and must go through the confirmed SMTP or '
+          + 'connector send path. Auto-send is not permitted.',
+      },
+    ],
+    // No `freshness`: this record is a LOCAL composition, not a provider-backed
+    // read, so it must not be classified as a fresh provider record (which would
+    // inflate the Personal Ops queue's freshProviderReads count). Drafts are
+    // composed locally from supplied fields and are session-local.
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Aggregated export for easy import in buildLanes()
+// ---------------------------------------------------------------------------
+
+export interface StyleReplyLaneAdditions {
+  readonly workflow: PersonalOpsWorkflow;
+  readonly liveRecord: PersonalOpsLiveRecord;
+}
+
+/**
+ * Returns both the workflow and live record for the style-reply lane.
+ * Call once per buildLanes() invocation; result is deterministic.
+ */
+export function buildStyleReplyLaneAdditions(hasEmailCapability: boolean): StyleReplyLaneAdditions {
+  return {
+    workflow: styleReplyWorkflow(hasEmailCapability),
+    liveRecord: styleReplyLiveRecord(hasEmailCapability),
+  };
+}