Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

14.8 KB
Raw Blame
import * as Match from "effect/Match";
import * as Data from "effect/Data";
import * as Predicate from "effect/Predicate";
import * as Effect from "effect/Effect";
import * as Schema from "effect/Schema";
import * as SchemaTransformation from "effect/SchemaTransformation";

import { AkeruMemoryTargetScope } from "./akeruMemory/base.ts";
import { AkeruToolApprovalClass, AkeruToolId } from "./akeruTools/catalog.ts";
import {
  BotId,
  IsoDateTime,
  MessageId,
  PositiveInt,
  ThreadId,
  TrimmedNonEmptyString,
  TurnId,
} from "./baseSchemas.ts";
import { McpServerId } from "./mcpServer.ts";
import { BotSandbox } from "./orchestration/roster.ts";
import { RuntimeMode } from "./orchestration/modelSelection.ts";

const DelegationPhase = Data.taggedEnum<AkeruDelegationPhase>();

export const AKERU_DELEGATION_MAX_DEPTH = 2;

export const AKERU_DELEGATION_MAX_CONCURRENCY = 3;

export const DelegationId = TrimmedNonEmptyString.pipe(Schema.brand("DelegationId"));

export type DelegationId = typeof DelegationId.Type;

/** @deprecated Lifecycle records use AkeruDelegationPhase. */
export const AkeruDelegationState = Schema.Literals([
  "queued",
  "running",
  "blocked",
  "failed",
  "canceled",
  "completed",
]);

export type AkeruDelegationState = typeof AkeruDelegationState.Type;

/** Whether a delegation has finished and can no longer change state. */
export const isTerminalDelegationState = (state: AkeruDelegationState): boolean =>
  state === "completed" || state === "failed" || state === "canceled";

/**
 * Finished delegations a shell snapshot keeps per parent thread, newest first.
 * Open delegations are always kept.
 */
export const SHELL_RECENT_TERMINAL_DELEGATIONS_PER_THREAD = 20;

/** What started a delegation: a parent bot's tool call or a scheduled routine. */
export const AkeruDelegationTrigger = Schema.Literals(["bot", "scheduled"]);

export type AkeruDelegationTrigger = typeof AkeruDelegationTrigger.Type;

export const AkeruDelegationAccessGrant = Schema.Struct({
  allowedToolIds: Schema.Array(Schema.suspend(() => AkeruToolId)),
  memoryScopes: Schema.Array(AkeruMemoryTargetScope),
  sandbox: Schema.NullOr(Schema.suspend((): Schema.Codec<BotSandbox> => BotSandbox)),
  runtimeMode: Schema.suspend((): Schema.Codec<RuntimeMode> => RuntimeMode),
  hasUserComputer: Schema.Boolean,
  enabledMcpServerIds: Schema.Array(McpServerId).pipe(
    Schema.withDecodingDefault(Effect.succeed([])),
  ),
  disabledMcpServerIds: Schema.Array(McpServerId),
  approvalCeiling: Schema.suspend(() => AkeruToolApprovalClass),
});

export type AkeruDelegationAccessGrant = typeof AkeruDelegationAccessGrant.Type;

export const AkeruDelegationFailureCode = Schema.Literals([
  "timeout",
  "denied",
  "child_failed",
  "parent_failed",
  "internal",
]);

export type AkeruDelegationFailureCode = typeof AkeruDelegationFailureCode.Type;

export const AkeruDelegationResult = Schema.Struct({
  summary: TrimmedNonEmptyString,
  childThreadId: ThreadId,
  childTurnId: Schema.NullOr(TurnId),
});

export type AkeruDelegationResult = typeof AkeruDelegationResult.Type;

export const AkeruDelegationFailure = Schema.Struct({
  failureCode: AkeruDelegationFailureCode,
  message: TrimmedNonEmptyString,
});

export type AkeruDelegationFailure = typeof AkeruDelegationFailure.Type;

const AkeruDelegationRecordFields = {
  delegationId: DelegationId,
  parentDelegationId: Schema.NullOr(DelegationId),
  parentBotId: BotId,
  childBotId: BotId,
  parentThreadId: ThreadId,
  parentTurnId: TurnId,
  ancestorBotIds: Schema.Array(BotId),
  depth: PositiveInt.check(Schema.isLessThanOrEqualTo(AKERU_DELEGATION_MAX_DEPTH)),
  task: TrimmedNonEmptyString,
  expectedResult: TrimmedNonEmptyString,
  deadline: Schema.NullOr(IsoDateTime),
  access: AkeruDelegationAccessGrant,
  billedBotId: BotId,
  keep: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
  /** Parent chat message the work card sits under. Null places it by parentTurnId. */
  anchorMessageId: Schema.NullOr(MessageId).pipe(Schema.withDecodingDefault(Effect.succeed(null))),
  /** The Failed or Canceled delegation this one retries. The original is never mutated. */
  retryOfDelegationId: Schema.NullOr(DelegationId).pipe(
    Schema.withDecodingDefault(Effect.succeed(null)),
  ),
  trigger: AkeruDelegationTrigger.pipe(Schema.withDecodingDefault(Effect.succeed("bot" as const))),
  createdAt: IsoDateTime,
  updatedAt: IsoDateTime,
} as const;

export const AkeruDelegationPhase = Schema.TaggedUnion({
  Queued: {},
  Running: {
    childThreadId: ThreadId,
    childTurnId: Schema.NullOr(TurnId),
    startedAt: IsoDateTime,
    progress: Schema.NullOr(TrimmedNonEmptyString),
  },
  Blocked: {
    childThreadId: ThreadId,
    childTurnId: Schema.NullOr(TurnId),
    startedAt: IsoDateTime,
    reason: TrimmedNonEmptyString,
  },
  Completed: {
    childThreadId: ThreadId,
    childTurnId: Schema.NullOr(TurnId),
    startedAt: IsoDateTime,
    completedAt: IsoDateTime,
    result: AkeruDelegationResult,
    acknowledgedAt: Schema.NullOr(IsoDateTime),
  },
  Failed: {
    childThreadId: Schema.NullOr(ThreadId),
    childTurnId: Schema.NullOr(TurnId),
    startedAt: Schema.NullOr(IsoDateTime),
    completedAt: IsoDateTime,
    failure: AkeruDelegationFailure,
    acknowledgedAt: Schema.NullOr(IsoDateTime).pipe(
      Schema.withDecodingDefault(Effect.succeed(null)),
    ),
  },
  Canceled: {
    childThreadId: Schema.NullOr(ThreadId),
    childTurnId: Schema.NullOr(TurnId),
    startedAt: Schema.NullOr(IsoDateTime),
    completedAt: IsoDateTime,
    canceledBy: Schema.Literals(["user", "parent-bot", "parent-turn-failed"]),
  },
});

export type AkeruDelegationPhase = typeof AkeruDelegationPhase.Type;

const TaggedDelegationRecord = Schema.Struct({
  ...AkeruDelegationRecordFields,
  phase: AkeruDelegationPhase,
});

const LegacyDelegationRecord = Schema.Struct({
  ...AkeruDelegationRecordFields,
  childThreadId: Schema.NullOr(ThreadId),
  childTurnId: Schema.NullOr(TurnId),
  state: Schema.Literals(["queued", "running", "blocked", "failed", "canceled", "completed"]),
  result: Schema.NullOr(AkeruDelegationResult),
  failure: Schema.NullOr(AkeruDelegationFailure),
  startedAt: Schema.NullOr(IsoDateTime),
  completedAt: Schema.NullOr(IsoDateTime),
  // Phase details the flat wire form carries so replay keeps them. Older clients ignore them.
  progress: Schema.optionalKey(Schema.NullOr(TrimmedNonEmptyString)),
  blockedReason: Schema.optionalKey(TrimmedNonEmptyString),
  acknowledgedAt: Schema.optionalKey(Schema.NullOr(IsoDateTime)),
  canceledBy: Schema.optionalKey(Schema.Literals(["user", "parent-bot", "parent-turn-failed"])),
});

type LegacyDelegationRecord = typeof LegacyDelegationRecord.Type;

type TaggedDelegationRecord = typeof TaggedDelegationRecord.Type;

const legacyPhase = (legacy: LegacyDelegationRecord): AkeruDelegationPhase => {
  const childThreadId = legacy.childThreadId ?? legacy.result?.childThreadId ?? null;
  const startedAt = legacy.startedAt ?? legacy.createdAt;
  const completedAt = legacy.completedAt ?? legacy.updatedAt;

  switch (legacy.state) {
    case "queued":
      return DelegationPhase.Queued();
    case "running":
    case "blocked":
      if (childThreadId === null) return DelegationPhase.Queued();

      return legacy.state === "running"
        ? DelegationPhase.Running({
            childThreadId,
            childTurnId: legacy.childTurnId,
            startedAt,
            progress: legacy.progress ?? null,
          })
        : DelegationPhase.Blocked({
            childThreadId,
            childTurnId: legacy.childTurnId,
            startedAt,
            reason: legacy.blockedReason ?? legacy.failure?.message ?? "The bot is blocked.",
          });
    case "completed":
      if (childThreadId !== null && legacy.result !== null) {
        return DelegationPhase.Completed({
          childThreadId,
          childTurnId: legacy.childTurnId,
          startedAt,
          completedAt,
          result: legacy.result,
          acknowledgedAt: legacy.acknowledgedAt ?? null,
        });
      }

      return DelegationPhase.Failed({
        childThreadId,
        childTurnId: legacy.childTurnId,
        startedAt: legacy.startedAt,
        completedAt,
        failure: { failureCode: "child_failed", message: "The bot did not return a result." },
        acknowledgedAt: null,
      });
    case "failed":
      return DelegationPhase.Failed({
        childThreadId,
        childTurnId: legacy.childTurnId,
        startedAt: legacy.startedAt,
        completedAt,
        failure: legacy.failure ?? {
          failureCode: "child_failed",
          message: "The bot did not return a result.",
        },
        acknowledgedAt: null,
      });
    case "canceled":
      return DelegationPhase.Canceled({
        childThreadId,
        childTurnId: legacy.childTurnId,
        startedAt: legacy.startedAt,
        completedAt,
        canceledBy: legacy.canceledBy ?? "user",
      });
  }
};

const LegacyToTagged = LegacyDelegationRecord.pipe(
  Schema.decodeTo(
    Schema.toType(TaggedDelegationRecord),
    SchemaTransformation.transform<TaggedDelegationRecord, LegacyDelegationRecord>({
      decode: (legacy) => {
        const {
          childThreadId: _childThreadId,
          childTurnId: _childTurnId,
          state: _state,
          result: _result,
          failure: _failure,
          startedAt: _startedAt,
          completedAt: _completedAt,
          progress: _progress,
          blockedReason: _blockedReason,
          acknowledgedAt: _acknowledgedAt,
          canceledBy: _canceledBy,
          ...base
        } = legacy;

        return { ...base, phase: legacyPhase(legacy) };
      },
      encode: ({ phase, ...base }) => ({
        ...base,
        childThreadId: isQueuedPhase(phase) ? null : phase.childThreadId,
        childTurnId: isQueuedPhase(phase) ? null : phase.childTurnId,
        state: akeruDelegationStateOf(phase),
        result: Predicate.isTagged(phase, "Completed") ? phase.result : null,
        failure: Predicate.isTagged(phase, "Failed") ? phase.failure : null,
        startedAt: isQueuedPhase(phase) ? null : phase.startedAt,
        completedAt: "completedAt" in phase ? phase.completedAt : null,
        ...(Predicate.isTagged(phase, "Running") ? { progress: phase.progress } : {}),
        ...(Predicate.isTagged(phase, "Blocked") ? { blockedReason: phase.reason } : {}),
        ...(Predicate.isTagged(phase, "Completed") ? { acknowledgedAt: phase.acknowledgedAt } : {}),
        ...(Predicate.isTagged(phase, "Canceled") ? { canceledBy: phase.canceledBy } : {}),
      }),
    }),
  ),
);

/** Lowercase state name for a phase, as used by activity kinds and tool payloads. */
export const akeruDelegationStateOf = (phase: AkeruDelegationPhase): AkeruDelegationState => {
  return Match.value(phase).pipe(
    Match.tagsExhaustive({
      Queued: () => {
        return "queued" as const;
      },
      Running: () => {
        return "running" as const;
      },
      Blocked: () => {
        return "blocked" as const;
      },
      Completed: () => {
        return "completed" as const;
      },
      Failed: () => {
        return "failed" as const;
      },
      Canceled: () => {
        return "canceled" as const;
      },
    }),
  );
};

export const AkeruDelegationRecord = Schema.Union([LegacyToTagged, TaggedDelegationRecord]);

export type AkeruDelegationRecord = typeof AkeruDelegationRecord.Type;

export const AKERU_DELEGATION_TRANSITIONS = {
  Queued: new Set(["Running", "Failed", "Canceled"]),
  Running: new Set(["Blocked", "Completed", "Failed", "Canceled"]),
  Blocked: new Set(["Running", "Failed", "Canceled"]),
} as const;

export const AKERU_DELEGATION_TERMINAL_PHASES: ReadonlySet<AkeruDelegationPhase["_tag"]> = new Set([
  "Completed",
  "Failed",
  "Canceled",
]);

export const isAkeruDelegationTerminal = (phase: AkeruDelegationPhase): boolean =>
  AKERU_DELEGATION_TERMINAL_PHASES.has(phase._tag);

/**
 * A finished child result the parent bot has not received yet. Completed and
 * failed work is delivered to the parent's next turn; user cancels are not,
 * because the user already knows about them.
 */
export const isAkeruDelegationResultPending = (
  record: AkeruDelegationRecord,
): record is AkeruDelegationRecord & {
  readonly phase: Extract<AkeruDelegationPhase, { _tag: "Completed" | "Failed" }>;
} =>
  (Predicate.isTagged(record.phase, "Completed") || Predicate.isTagged(record.phase, "Failed")) &&
  record.phase.acknowledgedAt === null;

/** Stamps a pending result as delivered to the parent bot. */
export const acknowledgeAkeruDelegation = (
  record: AkeruDelegationRecord,
  acknowledgedAt: string,
): AkeruDelegationRecord =>
  isAkeruDelegationResultPending(record)
    ? {
        ...record,
        phase: { ...record.phase, acknowledgedAt },
        updatedAt:
          Date.parse(acknowledgedAt) >= Date.parse(record.updatedAt)
            ? acknowledgedAt
            : record.updatedAt,
      }
    : record;

/**
 * Returns an acknowledged result to pending when the turn that acknowledged it
 * never reached its provider, so the next parent turn receives it instead.
 */
export const releaseAkeruDelegationAcknowledgement = (
  record: AkeruDelegationRecord,
): AkeruDelegationRecord =>
  (Predicate.isTagged(record.phase, "Completed") || Predicate.isTagged(record.phase, "Failed")) &&
  record.phase.acknowledgedAt !== null
    ? { ...record, phase: { ...record.phase, acknowledgedAt: null } }
    : record;

/**
 * True while any child delegation started from this parent thread is still
 * working. Derived from the delegation records so every client and the server
 * agree without a second persisted flag.
 */
export const isThreadWaitingOnChildren = (
  delegations: ReadonlyArray<AkeruDelegationRecord>,
  parentThreadId: ThreadId,
): boolean =>
  delegations.some(
    (delegation) =>
      delegation.parentThreadId === parentThreadId && !isAkeruDelegationTerminal(delegation.phase),
  );

export class AkeruDelegationContextTooLongError extends Schema.TaggedErrorClass<AkeruDelegationContextTooLongError>()(
  "AkeruDelegationContextTooLongError",
  {
    length: Schema.Number,
    maxLength: Schema.Number,
  },
) {
  override get message(): string {
    return `Delegation context is ${this.length} characters; the limit is ${this.maxLength}. Shorten it or put the details in the task.`;
  }
}

/** SendToAgent names a bot whose provider runs on the legacy bridge. */
export class AkeruDelegationProviderUnsupportedError extends Schema.TaggedErrorClass<AkeruDelegationProviderUnsupportedError>()(
  "AkeruDelegationProviderUnsupportedError",
  {
    botName: Schema.String,
    driverKind: Schema.String,
  },
) {
  override get message(): string {
    return `${this.botName} runs on the ${this.driverKind} provider, which cannot receive handed-off work. Do the work yourself or pick a bot on another provider.`;
  }
}

function isQueuedPhase(
  value: AkeruDelegationPhase,
): value is Extract<AkeruDelegationPhase, { readonly _tag: "Queued" }> {
  return Predicate.isTagged(value, "Queued");
}