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.

7.5 KB
Raw Blame
import type { AgentId } from "./types.js";

export type TaskId = string;
export type DocumentId = string;

export interface MetaExecutionContextRef {
  readonly kind: "meta";
  readonly agentId: AgentId;
  readonly roomId: string;
}

export interface AlterEgoExecutionContextRef {
  readonly kind: "alter_ego";
  readonly agentId: AgentId;
  readonly taskId: TaskId;
}

export interface DocumentExecutionContextRef {
  readonly kind: "document";
  readonly agentId: AgentId;
  readonly documentId: DocumentId;
}

export type ExecutionContextRef =
  | MetaExecutionContextRef
  | AlterEgoExecutionContextRef
  | DocumentExecutionContextRef;

declare const executionContextKeyBrand: unique symbol;

export type ExecutionContextKey = string & {
  readonly [executionContextKeyBrand]: true;
};

export function assertExecutionContextRef(
  value: unknown,
): asserts value is ExecutionContextRef {
  if (!isPlainRecord(value)) {
    throw new TypeError("ExecutionContextRef must be an object");
  }
  if (value.kind === "meta") {
    assertExactKeys(
      value,
      ["kind", "agentId", "roomId"],
      "meta ExecutionContextRef",
    );
    assertNonEmptyId(value.agentId, "ExecutionContextRef.agentId");
    assertNonEmptyId(value.roomId, "ExecutionContextRef.roomId");
    return;
  }
  if (value.kind === "alter_ego") {
    assertExactKeys(
      value,
      ["kind", "agentId", "taskId"],
      "alter_ego ExecutionContextRef",
    );
    assertNonEmptyId(value.agentId, "ExecutionContextRef.agentId");
    assertNonEmptyId(value.taskId, "ExecutionContextRef.taskId");
    return;
  }
  if (value.kind === "document") {
    assertExactKeys(
      value,
      ["kind", "agentId", "documentId"],
      "document ExecutionContextRef",
    );
    assertNonEmptyId(value.agentId, "ExecutionContextRef.agentId");
    assertNonEmptyId(value.documentId, "ExecutionContextRef.documentId");
    return;
  }
  throw new TypeError(
    'ExecutionContextRef.kind must be "meta", "alter_ego", or "document"',
  );
}

export const encodeExecutionContextRef = (
  ref: ExecutionContextRef,
): ExecutionContextKey => {
  assertExecutionContextRef(ref);
  return JSON.stringify(
    ref.kind === "meta"
      ? ["meta", ref.agentId, "room", ref.roomId]
      : ref.kind === "alter_ego"
        ? ["alter_ego", ref.agentId, ref.taskId]
        : ["document", ref.agentId, ref.documentId],
  ) as ExecutionContextKey;
};

export const decodeExecutionContextKey = (
  key: string,
): Readonly<ExecutionContextRef> => {
  if (typeof key !== "string" || key.length === 0) {
    throw new TypeError("ExecutionContextKey must be a non-empty string");
  }

  let decoded: unknown;
  try {
    decoded = JSON.parse(key) as unknown;
  } catch (error) {
    throw new TypeError("ExecutionContextKey must be valid JSON", {
      cause: error,
    });
  }

  let ref: ExecutionContextRef;
  if (
    Array.isArray(decoded) &&
    decoded.length === 4 &&
    decoded[0] === "meta" &&
    decoded[2] === "room"
  ) {
    assertNonEmptyId(decoded[1], "ExecutionContextKey agentId");
    assertNonEmptyId(decoded[3], "ExecutionContextKey roomId");
    ref = { kind: "meta", agentId: decoded[1], roomId: decoded[3] };
  } else if (
    Array.isArray(decoded) &&
    decoded.length === 3 &&
    decoded[0] === "alter_ego"
  ) {
    assertNonEmptyId(decoded[1], "ExecutionContextKey agentId");
    assertNonEmptyId(decoded[2], "ExecutionContextKey taskId");
    ref = {
      kind: "alter_ego",
      agentId: decoded[1],
      taskId: decoded[2],
    };
  } else if (
    Array.isArray(decoded) &&
    decoded.length === 3 &&
    decoded[0] === "document"
  ) {
    assertNonEmptyId(decoded[1], "ExecutionContextKey agentId");
    assertNonEmptyId(decoded[2], "ExecutionContextKey documentId");
    ref = {
      kind: "document",
      agentId: decoded[1],
      documentId: decoded[2],
    };
  } else {
    throw new TypeError("ExecutionContextKey has an unsupported shape");
  }

  if (encodeExecutionContextRef(ref) !== key) {
    throw new TypeError("ExecutionContextKey is not canonical");
  }
  return Object.freeze(ref);
};

function assertNonEmptyId(
  value: unknown,
  field: string,
): asserts value is string {
  if (typeof value !== "string" || value.length === 0) {
    throw new TypeError(`${field} must be a non-empty string`);
  }
}

const assertExactKeys = (
  value: Record<string, unknown>,
  expected: readonly string[],
  field: string,
): void => {
  const allowed = new Set(expected);
  const unknownKey = Object.keys(value).find((key) => !allowed.has(key));
  if (unknownKey !== undefined) {
    throw new TypeError(`${field}.${unknownKey} is not supported`);
  }
  const missingKey = expected.find((key) => !Object.hasOwn(value, key));
  if (missingKey !== undefined) {
    throw new TypeError(`${field}.${missingKey} is required`);
  }
};

// A plain object only: unlike service-kit isRecord, class instances are refused.
const isPlainRecord = (value: unknown): value is Record<string, unknown> => {
  if (typeof value !== "object" || value === null || Array.isArray(value)) {
    return false;
  }
  const prototype = Object.getPrototypeOf(value) as object | null;
  return prototype === Object.prototype || prototype === null;
};

export type ContextTargetResidency = "active" | "suspended";
export type MetaRoomKind = "direct" | "collaboration";

/**
 * TeamHub-trusted identity of the shared Task directory a Context reads
 * (Room Meta) or writes (alter_ego of a Meta-coordinated Task).
 */
export type SharedTaskScope =
  | {
      readonly version: 1;
      readonly tenantId: string;
      readonly agentId: string;
      readonly originRoomId: string;
      readonly role: "meta";
    }
  | {
      readonly version: 1;
      readonly tenantId: string;
      readonly agentId: string;
      readonly originRoomId: string;
      readonly role: "alter_ego";
      readonly taskId: string;
    };

export interface ExecutionContextRecord {
  readonly ref: ExecutionContextRef;
  readonly roomKind?: MetaRoomKind;
  readonly sharedTaskScope?: SharedTaskScope;
  readonly targetResidency: ContextTargetResidency;
  readonly terminalReason?: "room_deleted" | "context_deleted";
}

export interface EnsureExecutionContextResult {
  readonly created: boolean;
  readonly record: ExecutionContextRecord;
}

export interface ExecutionContextStore {
  ensure(
    ref: ExecutionContextRef,
    initialTargetResidency?: ContextTargetResidency,
  ): Promise<EnsureExecutionContextResult>;
  get(ref: ExecutionContextRef): Promise<ExecutionContextRecord | null>;
  list(): Promise<readonly ExecutionContextRecord[]>;
  listByAgent(agentId: string): Promise<readonly ExecutionContextRecord[]>;
  setTargetResidency(
    ref: ExecutionContextRef,
    targetResidency: ContextTargetResidency,
  ): Promise<"updated" | "not_found">;
  remove(ref: ExecutionContextRef): Promise<"removed" | "not_found">;
  removeByAgent(agentId: string): Promise<number>;
  subscribe?(
    listener: (record: Readonly<ExecutionContextRecord>) => void,
  ): () => void;
  /**
   * The record this store last observed, without a read. A store that
   * publishes through subscribe() keeps it current with every notification.
   */
  cached?(ref: ExecutionContextRef): Readonly<ExecutionContextRecord> | null;
  /**
   * Notifies lifecycle owners when this process stops holding a Context or
   * TeamHub rebinds it to a new Room membership; what was prepared for it
   * must stop.
   */
  subscribeUnbind?(
    listener: (ref: Readonly<ExecutionContextRef>) => void,
  ): () => void;
  /** Stops holding a suspended Context; queued work binds it again. */
  releaseIfIdle?(ref: ExecutionContextRef): Promise<boolean>;
  close(): Promise<void>;
}