Skip to content

Linger is An Open-Source Personal Agent That Runs Fully on Your PC. We aim to break Big Tech’s grip on AI by bringing powerful local AI to everyday computers through efficient model–harness co-design, so everyone can run their own.

20.6 KB
Raw Blame
import { Buffer } from "node:buffer";
import { randomUUID } from "node:crypto";
import { readFileSync } from "node:fs";
import path from "node:path";

import { isRecord } from "@linger/service-kit";

import { packageRoot } from "./paths.js";
import {
  ModelBudgetSpentError,
  schemaProblem,
  type ModelCallEffort,
  type ModelChain,
  type ModelRunBudget,
} from "./runtime-model-call.js";

/**
 * The memory Agent: one controlled loop for every kind of memory upkeep
 * (Wiki pages, memory.md, Tracking Items, ...). A task runs a bounded number
 * of steps. Each step is one structured model call that returns a group of
 * actions, like one turn of a deep agent that calls several tools. The
 * application runs the actions, checks every write as a proposal of a
 * registered object type, and feeds the results to the next step. Nothing
 * here stores anything: the caller's environment stages accepted proposals.
 */

/** A kind of memory a task may write. */
export interface AgentObjectType {
  /** Registry name, for example `wiki.client`. */
  readonly type: string;
  /** Rules for this type only; the shared principles come with the task. */
  readonly instructions: string;
  /** Strict JSON schema of one proposal's payload. */
  readonly payloadSchema: Readonly<Record<string, unknown>>;
}

/** A read or flow tool the environment runs for the model. */
export interface AgentTool {
  readonly name: string;
  readonly description: string;
  /** Strict JSON schema of the arguments object. */
  readonly argumentsSchema: Readonly<Record<string, unknown>>;
}

/** One task's configuration. Its limits keep every step within the budget. */
export interface AgentTask {
  /** Names the task in logs, for example `wiki.entity`. */
  readonly name: string;
  readonly instructions: string;
  readonly objects: readonly AgentObjectType[];
  readonly tools: readonly AgentTool[];
  readonly maxSteps: number;
  /** Actions one step may return. */
  readonly maxActions: number;
  /** Characters of one step's results that the next step reads. */
  readonly maxResultChars: number;
  readonly effort: ModelCallEffort;
  /** One step's model call. */
  readonly timeoutMs: number;
  /** Stops one step's reply past this many characters; omitted, no cap. */
  readonly maxOutputChars?: number;
}

/** What one action did, as the next step reads it. */
export interface AgentObservation {
  readonly ok: boolean;
  readonly content: string;
}

/** Runs the task's tools and checks its proposals. */
export interface AgentEnvironment {
  runTool(
    name: string,
    args: Readonly<Record<string, unknown>>,
    signal: AbortSignal,
  ): Promise<AgentObservation>;
  /** Validates one write and stages it when it passes. */
  propose(
    object: string,
    target: string,
    payload: Readonly<Record<string, unknown>>,
  ): Promise<AgentObservation>;
  /** What the task still owes; a finish waits while it says anything. */
  unfinished?(): string | undefined;
}

export interface AgentStepRecord {
  /** Each action as the model wrote it, a proposal without its payload. */
  readonly calls: readonly string[];
  readonly observations: readonly AgentObservation[];
  /** By position, the payload of each rejected proposal, so the next step
   * can fix its draft instead of writing it again from nothing. */
  readonly drafts?: readonly (string | undefined)[];
}

export interface AgentRunResult {
  readonly steps: readonly AgentStepRecord[];
  /** The model finished the task within its step limit. */
  readonly finished: boolean;
  readonly summary?: string;
  /** Proposals the environment accepted. */
  readonly accepted: number;
  /** Proposals the environment rejected; later steps may have fixed them. */
  readonly rejected: number;
}

type ParsedAction =
  | {
      readonly kind: "tool";
      readonly name: string;
      readonly args: Readonly<Record<string, unknown>>;
    }
  | {
      readonly kind: "propose";
      readonly object: string;
      readonly target: string;
      readonly payload: Readonly<Record<string, unknown>>;
    }
  | { readonly kind: "finish"; readonly summary: string };

const STEP_SCHEMA_NAME = "memory_agent_step";

/** A strict object schema: every property required, nothing else allowed. */
export function strictObject(
  properties: Readonly<Record<string, unknown>>,
): Record<string, unknown> {
  return {
    type: "object",
    additionalProperties: false,
    required: Object.keys(properties),
    properties,
  };
}

/** Up to `maxActions` actions of this task, as an array. */
function agentActionsSchema(task: AgentTask): Record<string, unknown> {
  const branches = [
    ...task.tools.map((tool) =>
      strictObject({
        tool: { type: "string", enum: [tool.name] },
        arguments: tool.argumentsSchema,
      }),
    ),
    ...task.objects.map((object) =>
      strictObject({
        tool: { type: "string", enum: ["propose"] },
        object: { type: "string", enum: [object.type] },
        target: { type: "string", minLength: 1, maxLength: 300 },
        payload: object.payloadSchema,
      }),
    ),
    strictObject({
      tool: { type: "string", enum: ["finish"] },
      summary: { type: "string", maxLength: 1_000 },
    }),
  ];
  return {
    type: "array",
    maxItems: task.maxActions,
    items: { anyOf: branches },
  };
}

/** The schema of one step: up to `maxActions` actions of this task. */
export function agentStepSchema(
  task: AgentTask,
  actions: Record<string, unknown> = agentActionsSchema(task),
): Record<string, unknown> {
  return strictObject({
    // Claude's structured output can send a long array as its JSON text and
    // then fail validation on every retry; parseActions reads either form,
    // and the step checks the text against the array schema.
    actions: { anyOf: [actions, { type: "string" }] },
  });
}

/** The fixed part of every step; the task input and history follow it. */
export function agentInstructions(task: AgentTask): string {
  const objects = task.objects
    .map((object) => `### ${object.type}\n\n${object.instructions.trim()}`)
    .join("\n\n");
  const tools = task.tools
    .map((tool) => `- \`${tool.name}\`: ${tool.description}`)
    .join("\n");
  return `${sharedPrinciples()}

${task.instructions.trim()}

## Objects you may write

${objects || "This task writes no objects."}

## Tools

${tools}
${task.objects.length ? "- `propose`: submit one write of an object above. `target` names the object (for a page, its path). The application checks it at once; an accepted proposal is kept, a rejected one comes back with its issues and must be resent in full.\n" : ""}- \`finish\`: end the task with a one-line summary. It may share a step with other actions.

## Step protocol

- Each reply is one JSON object \`{"actions": [...]}\` with at most ${task.maxActions} actions. Reads run first and together, then proposals in order, then finish.
- The results of a step come back with the next step. You have at most ${task.maxSteps} steps; when they run out the task ends, keeping only accepted proposals. A finish waits while a proposal of its step was rejected or the task still owes work; the next step says what is left.
- Do everything a step allows: read several things at once, submit several proposals at once, and finish in the same step as your last proposals.
- Never repeat a read that an earlier step already returned.`;
}

/** Runs one task to its end: finish, its step limit, or a model failure. */
export async function runAgentTask(request: {
  /** The queued model task every step runs in. */
  readonly model: ModelChain;
  /** Names this agent task's steps within the model task; unique per run. */
  readonly step: string;
  readonly task: AgentTask;
  /** The task's own evidence and context. Every step is one stateless call
   * that sends it again with the history: each call names a Runtime session
   * of its own, so Codex applies the reply cap while no thread carries one
   * call into the next. */
  readonly input: string;
  /** Tokens one step's call may hold; past 85% of it, older steps are
   * shortened. Omitted, half the default context window. */
  readonly maxInputTokens?: number;
  /** Once spent, no further step starts; the task then ends unfinished,
   * keeping its accepted proposals. */
  readonly budget?: ModelRunBudget;
  readonly environment: AgentEnvironment;
  readonly signal?: AbortSignal;
}): Promise<AgentRunResult> {
  const { task, environment } = request;
  const instructions = agentInstructions(task);
  const actionsSchema = agentActionsSchema(task);
  const schema = agentStepSchema(task, actionsSchema);
  const signal = request.signal ?? new AbortController().signal;
  // Session keys of this run never meet a thread an earlier run left open.
  const session = randomUUID();
  const steps: AgentStepRecord[] = [];
  /** Tool calls already run, by their text, with the step that ran them. */
  const ran = new Map<string, number>();
  let accepted = 0;
  let rejected = 0;
  for (let index = 0; index < task.maxSteps; index += 1) {
    signal.throwIfAborted();
    if (request.budget?.spent) break;
    const output = await callStep(
      request,
      session,
      instructions,
      schema,
      actionsSchema,
      steps,
      index,
    ).catch((error: unknown) => {
      if (error instanceof ModelBudgetSpentError) return undefined;
      throw error;
    });
    if (output === undefined) break;
    const actions = parseActions(output, task);
    const calls: string[] = [];
    const results: AgentObservation[] = [];
    const drafts: (string | undefined)[] = [];
    const tools = actions.filter((action) => action.kind === "tool");
    const toolResults = await Promise.all(
      tools.map(async (action): Promise<AgentObservation> => {
        const call = `${action.name} ${JSON.stringify(action.args)}`;
        const earlier = ran.get(call);
        if (earlier !== undefined)
          return {
            ok: true,
            content: `Same as in step ${earlier + 1}; its result is above.`,
          };
        ran.set(call, index);
        return environment.runTool(action.name, action.args, signal).catch(
          (error: unknown): AgentObservation => ({
            ok: false,
            content: errorText(error),
          }),
        );
      }),
    );
    tools.forEach((action, position) => {
      calls.push(`${action.name} ${JSON.stringify(action.args)}`);
      results.push(toolResults[position]!);
      drafts.push(undefined);
    });
    for (const action of actions) {
      if (action.kind !== "propose") continue;
      const result = await environment
        .propose(action.object, action.target, action.payload)
        .catch(
          (error: unknown): AgentObservation => ({
            ok: false,
            content: errorText(error),
          }),
        );
      if (result.ok) accepted += 1;
      else rejected += 1;
      calls.push(`propose ${action.object} ${action.target}`);
      results.push(result);
      drafts.push(result.ok ? undefined : JSON.stringify(action.payload));
    }
    // A rejected proposal or owed work gets the next step, even after finish.
    const more = index + 1 < task.maxSteps;
    const fixable =
      more &&
      results.some(
        (result, position) =>
          !result.ok && calls[position]!.startsWith("propose "),
      );
    const finish = actions.find((action) => action.kind === "finish");
    const owed =
      more && !fixable && (finish || actions.length === 0)
        ? environment.unfinished?.()
        : undefined;
    if (owed) {
      calls.push("finish");
      results.push({ ok: false, content: `Not done yet: ${owed}` });
    } else if (fixable && finish) {
      calls.push("finish");
      results.push({
        ok: false,
        content: "Not done yet: resend the rejected proposals above, fixed",
      });
    }
    steps.push({
      calls,
      observations: fitResults(results, task.maxResultChars),
      drafts,
    });
    if (fixable || owed) continue;
    // A task that reports what it owes ends once nothing is owed; waiting for
    // the model to say finish would cost another call.
    if (environment.unfinished && !environment.unfinished())
      return {
        steps,
        finished: true,
        ...(finish ? { summary: finish.summary } : {}),
        accepted,
        rejected,
      };
    if (finish)
      return {
        steps,
        finished: true,
        summary: finish.summary,
        accepted,
        rejected,
      };
    if (actions.length === 0)
      return { steps, finished: true, accepted, rejected };
  }
  return { steps, finished: false, accepted, rejected };
}

/** One step's call; the chain's kind retries and corrects it. */
async function callStep(
  request: Parameters<typeof runAgentTask>[0],
  session: string,
  instructions: string,
  schema: Record<string, unknown>,
  actionsSchema: Record<string, unknown>,
  steps: readonly AgentStepRecord[],
  index: number,
): Promise<Record<string, unknown>> {
  const { output } = await request.model.call({
    step: `${request.step}/${index + 1}`,
    effort: request.task.effort,
    instructions,
    input: stepInput(request, instructions, steps, index),
    schemaName: STEP_SCHEMA_NAME,
    outputSchema: schema,
    validate: (output) => {
      if (typeof output.actions !== "string") return undefined;
      const actions = actionList(output.actions);
      if (actions === undefined)
        return "`actions` is text that is not a JSON array; send `actions` as an array of action objects";
      const problem = schemaProblem(actionsSchema, actions);
      return problem
        ? `\`actions\` text does not match the action schema: ${problem}; send \`actions\` as an array of action objects`
        : undefined;
    },
    timeoutMs: request.task.timeoutMs,
    ...(request.budget ? { budget: request.budget } : {}),
    ...(request.task.maxOutputChars === undefined
      ? {}
      : { maxOutputChars: request.task.maxOutputChars }),
    // One turn per session: the reply cap applies and nothing accumulates.
    sessionKey: `${session}/${index + 1}`,
  });
  return output;
}

/** Share of a step's token budget past which older steps are shortened. */
const HISTORY_COMPACT_SHARE = 0.85;

/**
 * One step's input: the task input, the steps so far, and where it stands.
 * Older steps lose their results, then their actions, while the call would
 * pass 85% of its budget; the latest step stays whole, and a rejected draft
 * stays until its object is proposed again.
 */
function stepInput(
  request: Parameters<typeof runAgentTask>[0],
  instructions: string,
  steps: readonly AgentStepRecord[],
  index: number,
): string {
  const budget = Math.floor(
    (request.maxInputTokens ?? taskTokens(undefined)) * HISTORY_COMPACT_SHARE,
  );
  const step =
    index + 1 < request.task.maxSteps
      ? `This is step ${index + 1} of at most ${request.task.maxSteps}.`
      : `This is the last step (${index + 1} of ${request.task.maxSteps}). Results of reads would come too late, so act now on what you already have.`;
  // What the task still owes after the steps so far, so the model need not
  // infer it from the history. A task owing nothing has already ended.
  const owed = steps.length ? request.environment.unfinished?.() : undefined;
  const status = owed ? `Still to do: ${owed}.\n\n` : "";
  const compose = (detail: HistoryDetail) =>
    `${request.input.trim()}

${renderHistory(steps, detail)}

${status}${step}`;
  let input = compose("full");
  for (const detail of ["calls", "latest"] as const) {
    if (estimateTokens(instructions) + estimateTokens(input) <= budget) break;
    input = compose(detail);
  }
  return input;
}

/** How much of the steps before the latest one the history keeps. */
type HistoryDetail = "full" | "calls" | "latest";

function renderHistory(
  steps: readonly AgentStepRecord[],
  detail: HistoryDetail,
): string {
  if (steps.length === 0) return "## Previous steps\n\nNone yet.";
  const last = steps.length - 1;
  /** The later step that proposed the same object again, if any. */
  const resentIn = (index: number, call: string) => {
    if (!call.startsWith("propose ")) return -1;
    return steps.findIndex(
      (later, position) => position > index && later.calls.includes(call),
    );
  };
  const rendered = steps.map((step, index) => {
    if (index < last && detail === "latest") return undefined;
    const results = index === last || detail === "full";
    const actions = step.calls.length
      ? step.calls
          .map((call, position) => {
            const observation = step.observations[position];
            const status = observation?.ok ? "ok" : "rejected";
            // A rejected draft stays until its object is proposed again; the
            // later proposal's result supersedes the older issues.
            const resent = resentIn(index, call);
            if (!observation?.ok && resent >= 0)
              return `- ${call}\n  rejected; resent in step ${resent + 1}`;
            const draft = step.drafts?.[position];
            return `- ${call}\n  ${results ? `${status}: ${indent(observation?.content ?? "")}` : `${status} (result shortened to fit the context)`}${draft ? `\n  Your rejected draft, to fix and resend in full: ${draft}` : ""}`;
          })
          .join("\n")
      : "- (no actions)";
    return `### Step ${index + 1}\n\n${actions}`;
  });
  const omitted = rendered.filter((step) => step === undefined).length;
  return `## Previous steps\n\n${[
    ...(omitted
      ? [
          `Steps 1 to ${omitted} are omitted to fit the context; their accepted proposals are kept.`,
        ]
      : []),
    ...rendered.filter((step): step is string => step !== undefined),
  ].join("\n\n")}`;
}

function parseActions(
  output: Readonly<Record<string, unknown>>,
  task: AgentTask,
): ParsedAction[] {
  const actions = actionList(output.actions) ?? [];
  const tools = new Set(task.tools.map((tool) => tool.name));
  const objects = new Set(task.objects.map((object) => object.type));
  const parsed: ParsedAction[] = [];
  for (const value of actions.slice(0, task.maxActions)) {
    if (!isRecord(value) || typeof value.tool !== "string") continue;
    if (value.tool === "finish") {
      parsed.push({
        kind: "finish",
        summary: typeof value.summary === "string" ? value.summary : "",
      });
    } else if (value.tool === "propose") {
      if (
        typeof value.object === "string" &&
        objects.has(value.object) &&
        typeof value.target === "string" &&
        isRecord(value.payload)
      )
        parsed.push({
          kind: "propose",
          object: value.object,
          target: value.target,
          payload: value.payload,
        });
    } else if (tools.has(value.tool) && isRecord(value.arguments)) {
      parsed.push({ kind: "tool", name: value.tool, args: value.arguments });
    }
  }
  return parsed;
}

/** A step's actions, given as an array or as the JSON text of one;
 * undefined when the text is not a JSON array. */
function actionList(value: unknown): unknown[] | undefined {
  if (Array.isArray(value)) return value;
  if (typeof value !== "string") return [];
  try {
    const parsed: unknown = JSON.parse(value);
    return Array.isArray(parsed) ? parsed : undefined;
  } catch {
    return undefined;
  }
}

/** Cuts a step's results to one shared character budget. */
function fitResults(
  results: readonly AgentObservation[],
  maxChars: number,
): AgentObservation[] {
  if (results.length === 0) return [];
  const each = Math.max(400, Math.floor(maxChars / results.length));
  return results.map((result) =>
    result.content.length <= each
      ? result
      : {
          ...result,
          content: `${result.content.slice(0, each)}\n…[${result.content.length - each} more characters cut; read a narrower range]`,
        },
  );
}

function indent(text: string): string {
  return text.trim().replaceAll("\n", "\n  ");
}

function errorText(error: unknown): string {
  return error instanceof Error ? error.message : String(error);
}

let principles: string | undefined;

/** The rules every memory task shares (evidence, what not to keep, conflicts). */
export function sharedPrinciples(): string {
  principles ??= readFileSync(
    path.join(packageRoot, "prompts", "memory-agent", "principles.md"),
    "utf8",
  ).trim();
  return principles;
}

/** The context window assumed when the Agent model's is unknown. */
export const DEFAULT_CONTEXT_WINDOW = 200_000;

/** What one model task may hold: half the model's context window. The other
 * half stays free for the Runtime's own prompt, the reply and estimation
 * error. */
export function taskTokens(contextWindow: number | undefined): number {
  return Math.floor((contextWindow ?? DEFAULT_CONTEXT_WINDOW) / 2);
}

/** UTF-8 bytes / 3: conservative for mixed Chinese and English text. */
export function estimateTokens(text: string): number {
  return Math.ceil(Buffer.byteLength(text, "utf8") / 3);
}