Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

8.5 KB
Raw Blame
/**
 * TaskSurface — the feedback contract, implemented once.
 *
 * Every channel used to get its own copy of "begin task / deliver / pause /
 * fail" inside Agent.handleMessage, and the copies drifted: verification
 * evidence reached the CLI only, pause banners were swallowed by Telegram's
 * status card, and Discord/Slack diverged from Signal. The agent now talks
 * to one surface; channels render, they do not decide.
 *
 * States: begin → (steps, via the channel's own feedback) → done | pause | fail.
 * done carries evidence (verification note, trace id); pause and fail are
 * always persistent messages, never status-card notices.
 */
import type { Channel } from '../channels/base.js';
import type { ChannelType } from '../types/index.js';
import { logger } from '../utils/logger.js';

export interface CompletionMetaLike {
  provider: string;
  model: string;
  inputTokens: number;
  outputTokens: number;
  totalTokens: number;
  /** Input tokens served from the provider's prompt cache (#296), when known. */
  cachedInputTokens?: number;
  budgetUsed: number;
  budgetTotal: number;
  budgetPercentage: number;
}

export interface DoneInput {
  finalText: string;
  elapsedMs: number;
  stepCount: number;
  meta: CompletionMetaLike;
  /** "npm test ✓" style note; shown on every surface, not only the CLI. */
  verificationNote?: string;
  /** Short id resolvable with /trace. */
  traceId: string;
  /** The CLI already streamed the text; do not send it again. */
  alreadyStreamed: boolean;
  /** Show the completion banner even for a short task (Mercury Code execution). */
  forceBanner?: boolean;
}

export interface TaskSurface {
  readonly kind: 'cli' | 'web' | 'messaging' | 'plain' | 'none';
  begin(): void;
  done(input: DoneInput): Promise<void>;
  /** Persistent pause/failure banner; flushes deferred streamed text first. */
  pause(banner: string): Promise<void>;
  /** Returns whether the message was delivered (web may report false). */
  fail(message: string): Promise<boolean>;
}

/** A task is "substantial" when it earns a completion banner. */
export const isSubstantialTask = (stepCount: number, elapsedMs: number): boolean => stepCount >= 3 && elapsedMs >= 30_000;

/** Evidence footer appended to the final text on surfaces without a banner slot. */
export function evidenceFooter(verificationNote: string | undefined, traceId: string): string {
  const parts = [verificationNote ? `Verification: ${verificationNote}` : null, `/trace ${traceId}`].filter(Boolean);
  return `_${parts.join(' · ')}_`;
}

interface MessagingTaskChannel extends Channel {
  beginTask(targetId?: string): void;
  endTask(targetId?: string): void;
  resetStepCounter(targetId?: string): void;
  popDeferredResponse(targetId?: string): string | undefined;
  deferResponse?(targetId: string | undefined, content: string): void;
  cleanupEphemeralMessages?(targetId?: string): Promise<void>;
  sendCompletion(elapsedMs: number, stepCount: number, targetId?: string, meta?: CompletionMetaLike): Promise<void>;
}

interface CliTaskChannel extends Channel {
  sendCompletion(elapsedMs: number, stepCount: number, meta?: CompletionMetaLike, outcome?: 'complete' | 'steps-paused', verificationNote?: string): void;
}

interface WebTaskChannel extends Channel {
  sendError(message: string, targetId?: string): boolean;
  /** The final reply, with what it cost (older web channels ignore `usage`). */
  send(content: string, targetId?: string, elapsedMs?: number, usage?: Record<string, unknown>): Promise<void>;
}

const hasFn = (obj: unknown, name: string): boolean => typeof (obj as Record<string, unknown> | null)?.[name] === 'function';

function isMessagingTaskChannel(channel: Channel): channel is MessagingTaskChannel {
  return ['beginTask', 'endTask', 'resetStepCounter', 'popDeferredResponse', 'sendCompletion'].every((n) => hasFn(channel, n));
}

const warnSend = (e: unknown) => logger.warn({ e }, 'channel send failed');

export function createTaskSurface(channel: Channel | undefined, channelType: ChannelType, channelId: string): TaskSurface {
  if (!channel || channelType === 'internal') return NONE;

  if (channelType === 'cli') {
    const cli = channel as CliTaskChannel;
    return {
      kind: 'cli',
      begin() {},
      async done({ finalText, elapsedMs, stepCount, meta, verificationNote, traceId, alreadyStreamed, forceBanner }) {
        if (!alreadyStreamed) await cli.send(finalText, channelId, elapsedMs);
        if (isSubstantialTask(stepCount, elapsedMs) || forceBanner) {
          const note = verificationNote ? `${verificationNote} · /trace ${traceId}` : `/trace ${traceId}`;
          cli.sendCompletion(elapsedMs, stepCount, meta, undefined, note);
        }
      },
      async pause(banner) {
        await cli.send(banner, channelId).catch(warnSend);
      },
      async fail(message) {
        await cli.send(message, channelId);
        return true;
      },
    };
  }

  if (channelType === 'web') {
    const web = channel as WebTaskChannel;
    return {
      kind: 'web',
      begin() {},
      async done({ finalText, elapsedMs, stepCount, meta }) {
        // What the reply cost, so a screen can show it as soon as it lands.
        await web.send(finalText, channelId, elapsedMs, {
          provider: meta.provider,
          model: meta.model,
          inputTokens: meta.inputTokens,
          cachedInputTokens: meta.cachedInputTokens ?? 0,
          outputTokens: meta.outputTokens,
          steps: stepCount,
          elapsedMs,
        });
      },
      async pause(banner) {
        await web.send(banner, channelId).catch(warnSend);
      },
      async fail(message) {
        return hasFn(web, 'sendError') ? web.sendError(message, channelId) : (await web.send(message, channelId), true);
      },
    };
  }

  if (isMessagingTaskChannel(channel)) {
    const ch = channel;
    const finish = (): string | undefined => {
      ch.endTask(channelId);
      ch.resetStepCounter(channelId);
      return ch.popDeferredResponse(channelId);
    };
    return {
      kind: 'messaging',
      begin() {
        ch.resetStepCounter(channelId);
        ch.beginTask(channelId);
      },
      async done({ finalText, elapsedMs, stepCount, meta, verificationNote, traceId }) {
        // Evidence used to reach the CLI only; messaging users got "done"
        // with nothing to back it. Carry it in the final text instead.
        const footer = verificationNote ? `\n\n${evidenceFooter(verificationNote, traceId)}` : '';
        const text = `${finalText}${footer}`;
        if (isSubstantialTask(stepCount, elapsedMs)) {
          // sendCompletion owns endTask + deferred flush + cleanup on these channels.
          if (ch.deferResponse) {
            if (text.trim()) ch.deferResponse(channelId, text);
          } else {
            await ch.stream((async function* () { yield text; })(), channelId);
          }
          await ch.sendCompletion(elapsedMs, stepCount, channelId, meta);
          return;
        }
        ch.endTask(channelId);
        // The streamed answer was parked while the task was active; it wins
        // over finalText, but must still carry the evidence footer (it used
        // to be dropped on every streaming messaging channel).
        const deferred = ch.popDeferredResponse(channelId);
        const responseText = deferred && deferred.trim() ? `${deferred}${footer}` : text;
        if (responseText && responseText.trim()) await ch.send(responseText, channelId, elapsedMs);
        if (stepCount > 0 && ch.cleanupEphemeralMessages) await ch.cleanupEphemeralMessages(channelId);
        ch.resetStepCounter(channelId);
      },
      async pause(banner) {
        // End the task FIRST: while a task is active these channels route
        // short sends into the status card (truncated) and delete the card
        // on finalize, which made a pause look like silence.
        const deferred = finish();
        if (deferred && deferred.trim()) await ch.send(deferred, channelId).catch(warnSend);
        await ch.send(banner, channelId).catch(warnSend);
      },
      async fail(message) {
        finish();
        await ch.send(message, channelId);
        return true;
      },
    };
  }

  return {
    kind: 'plain',
    begin() {},
    async done({ finalText, elapsedMs }) {
      await channel.send(finalText, channelId, elapsedMs);
    },
    async pause(banner) {
      await channel.send(banner, channelId).catch(warnSend);
    },
    async fail(message) {
      await channel.send(message, channelId);
      return true;
    },
  };
}

const NONE: TaskSurface = {
  kind: 'none',
  begin() {},
  async done() {},
  async pause() {},
  async fail() {
    return false;
  },
};