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.

15.2 KB
Raw Blame
import type { ExecutionContextRef } from "./context-ref.js";
import type {
  ActorId,
  AgentDefinition,
  AgentId,
  JsonObject,
  JsonValue,
} from "./types.js";

export interface SkillDescriptor {
  readonly skillId: string;
  readonly manifestVersion: string;
  readonly name: string;
  readonly packageName: string;
  readonly packageSha256: string;
  readonly config: JsonObject;
}

export interface McpDescriptor {
  readonly mcpId: string;
  readonly manifestVersion: string;
  readonly name: string;
  readonly transport: "streamable_http";
  readonly url: string;
  readonly allowedTools: readonly string[];
}

export interface GhostResources {
  readonly skills: readonly SkillDescriptor[];
  readonly mcpServers: readonly McpDescriptor[];
}

export interface GhostResourcesInput {
  readonly skills?: readonly SkillDescriptor[];
  readonly mcpServers?: readonly McpDescriptor[];
}

const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
const SKILL_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,511}$/;
const MANIFEST_VERSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/;
const PACKAGE_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
const SHA256_PATTERN = /^[a-f0-9]{64}$/;

export const materializeGhostResources = (
  input: GhostResourcesInput | undefined,
): Readonly<GhostResources> => {
  if (input !== undefined) {
    assertPlainObject(input, "resources");
    assertExactKeys(input, ["skills", "mcpServers"], "resources");
  }

  const sourceSkills = input?.skills === undefined ? [] : input.skills;
  if (!Array.isArray(sourceSkills)) {
    throw new TypeError("resources.skills must be an array");
  }
  const skills = sourceSkills.map((skill, index) =>
    snapshotSkill(skill, `resources.skills[${index}]`),
  );
  const skillIds = new Set<string>();
  const packageNames = new Set<string>();
  for (const skill of skills) {
    if (skillIds.has(skill.skillId)) {
      throw new TypeError(
        `resources.skills contains duplicate ${skill.skillId}`,
      );
    }
    if (packageNames.has(skill.packageName)) {
      throw new TypeError(
        `resources.skills contains duplicate packageName ${skill.packageName}`,
      );
    }
    skillIds.add(skill.skillId);
    packageNames.add(skill.packageName);
  }
  skills.sort(
    (left, right) =>
      compareStrings(left.skillId, right.skillId) ||
      compareStrings(left.manifestVersion, right.manifestVersion),
  );

  const sourceMcpServers =
    input?.mcpServers === undefined ? [] : input.mcpServers;
  if (!Array.isArray(sourceMcpServers)) {
    throw new TypeError("resources.mcpServers must be an array");
  }
  const mcpServers = sourceMcpServers.map((server, index) =>
    snapshotMcp(server, `resources.mcpServers[${index}]`),
  );
  const mcpIds = new Set<string>();
  for (const server of mcpServers) {
    if (mcpIds.has(server.mcpId)) {
      throw new TypeError(
        `resources.mcpServers contains duplicate ${server.mcpId}`,
      );
    }
    mcpIds.add(server.mcpId);
  }
  mcpServers.sort(
    (left, right) =>
      compareStrings(left.mcpId, right.mcpId) ||
      compareStrings(left.manifestVersion, right.manifestVersion),
  );

  return Object.freeze({
    skills: Object.freeze(skills),
    mcpServers: Object.freeze(mcpServers),
  });
};

export function assertGhostResources(
  value: unknown,
): asserts value is GhostResources {
  assertRecord(value, "resources");
  assertExactKeys(value, ["skills", "mcpServers"], "resources", true);
  if (!Array.isArray(value.skills)) {
    throw new TypeError("resources.skills must be an array");
  }
  if (!Array.isArray(value.mcpServers)) {
    throw new TypeError("resources.mcpServers must be an array");
  }
  materializeGhostResources({
    skills: value.skills as SkillDescriptor[],
    mcpServers: value.mcpServers as McpDescriptor[],
  });
}

const snapshotSkill = (
  value: SkillDescriptor,
  field: string,
): Readonly<SkillDescriptor> => {
  assertPlainObject(value, field);
  assertExactKeys(
    value,
    [
      "skillId",
      "manifestVersion",
      "name",
      "packageName",
      "packageSha256",
      "config",
    ],
    field,
    true,
  );
  assertIdentifier(value.skillId, `${field}.skillId`, SKILL_ID_PATTERN);
  assertManifestVersion(value.manifestVersion, `${field}.manifestVersion`);
  assertName(value.name, `${field}.name`);
  if (
    typeof value.packageName !== "string" ||
    value.packageName.length > 64 ||
    !PACKAGE_NAME_PATTERN.test(value.packageName)
  ) {
    throw new TypeError(`${field}.packageName is invalid`);
  }
  if (
    typeof value.packageSha256 !== "string" ||
    !SHA256_PATTERN.test(value.packageSha256)
  ) {
    throw new TypeError(`${field}.packageSha256 must be a lowercase SHA-256`);
  }
  const config = snapshotJsonObject(value.config, `${field}.config`);
  return Object.freeze({
    skillId: value.skillId,
    manifestVersion: value.manifestVersion,
    name: value.name,
    packageName: value.packageName,
    packageSha256: value.packageSha256,
    config,
  });
};

const snapshotMcp = (
  value: McpDescriptor,
  field: string,
): Readonly<McpDescriptor> => {
  assertPlainObject(value, field);
  assertExactKeys(
    value,
    ["mcpId", "manifestVersion", "name", "transport", "url", "allowedTools"],
    field,
    true,
  );
  assertIdentifier(value.mcpId, `${field}.mcpId`);
  assertManifestVersion(value.manifestVersion, `${field}.manifestVersion`);
  assertName(value.name, `${field}.name`);
  if (value.transport !== "streamable_http") {
    throw new TypeError(`${field}.transport must be "streamable_http"`);
  }
  assertMcpUrl(value.url, `${field}.url`);
  if (
    !Array.isArray(value.allowedTools) ||
    value.allowedTools.length === 0 ||
    value.allowedTools.length > 100
  ) {
    throw new TypeError(`${field}.allowedTools must contain 1 to 100 tools`);
  }
  const allowedTools = value.allowedTools.map((tool, index) => {
    if (typeof tool !== "string" || tool.length === 0) {
      throw new TypeError(
        `${field}.allowedTools[${index}] must be a non-empty string`,
      );
    }
    return tool;
  });
  if (new Set(allowedTools).size !== allowedTools.length) {
    throw new TypeError(`${field}.allowedTools must be unique`);
  }
  allowedTools.sort(compareStrings);
  return Object.freeze({
    mcpId: value.mcpId,
    manifestVersion: value.manifestVersion,
    name: value.name,
    transport: "streamable_http",
    url: value.url,
    allowedTools: Object.freeze(allowedTools),
  });
};

const snapshotJsonObject = (value: unknown, field: string): JsonObject => {
  assertRecord(value, field);
  return snapshotJsonValue(value, field, new WeakSet()) as JsonObject;
};

const snapshotJsonValue = (
  value: unknown,
  field: string,
  ancestors: WeakSet<object>,
): JsonValue => {
  if (
    value === null ||
    typeof value === "string" ||
    typeof value === "boolean"
  ) {
    return value;
  }
  if (typeof value === "number") {
    if (!Number.isFinite(value)) {
      throw new TypeError(`${field} contains a non-finite number`);
    }
    return Object.is(value, -0) ? 0 : value;
  }
  if (typeof value !== "object" || value === null) {
    throw new TypeError(`${field} must contain only JSON values`);
  }
  if (ancestors.has(value)) {
    throw new TypeError(`${field} must not contain a cycle`);
  }
  ancestors.add(value);
  try {
    if (Array.isArray(value)) {
      return Object.freeze(
        value.map((entry, index) =>
          snapshotJsonValue(entry, `${field}[${index}]`, ancestors),
        ),
      ) as unknown as JsonValue;
    }
    assertRecord(value, field);
    const result: JsonObject = {};
    for (const key of Object.keys(value).sort(compareStrings)) {
      Object.defineProperty(result, key, {
        configurable: false,
        enumerable: true,
        value: snapshotJsonValue(value[key], `${field}.${key}`, ancestors),
        writable: false,
      });
    }
    return Object.freeze(result);
  } finally {
    ancestors.delete(value);
  }
};

function assertIdentifier(
  value: unknown,
  field: string,
  pattern = ID_PATTERN,
): asserts value is string {
  if (typeof value !== "string" || !pattern.test(value)) {
    throw new TypeError(`${field} is invalid`);
  }
}

function assertManifestVersion(
  value: unknown,
  field: string,
): asserts value is string {
  if (typeof value !== "string" || !MANIFEST_VERSION_PATTERN.test(value)) {
    throw new TypeError(`${field} is invalid`);
  }
}

function assertName(value: unknown, field: string): asserts value is string {
  if (typeof value !== "string" || value.length === 0 || value.length > 120) {
    throw new TypeError(`${field} must contain 1 to 120 characters`);
  }
}

function assertMcpUrl(value: unknown, field: string): asserts value is string {
  if (typeof value !== "string" || value.length === 0 || value.length > 2_048) {
    throw new TypeError(`${field} is invalid`);
  }
  let parsed: URL;
  try {
    parsed = new URL(value);
  } catch (error) {
    throw new TypeError(`${field} is invalid`, { cause: error });
  }
  if (
    (parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
    parsed.username.length > 0 ||
    parsed.password.length > 0
  ) {
    throw new TypeError(`${field} must be an HTTP URL without credentials`);
  }
}

function assertRecord(
  value: unknown,
  field: string,
): asserts value is Record<string, unknown> {
  if (typeof value !== "object" || value === null || Array.isArray(value)) {
    throw new TypeError(`${field} must be an object`);
  }
  const prototype = Object.getPrototypeOf(value) as object | null;
  if (prototype !== Object.prototype && prototype !== null) {
    throw new TypeError(`${field} must be a plain object`);
  }
}

const assertExactKeys = (
  value: object,
  expected: readonly string[],
  field: string,
  requireAll = false,
): 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`);
  }
  if (!requireAll) return;
  const missingKey = expected.find((key) => !Object.hasOwn(value, key));
  if (missingKey !== undefined) {
    throw new TypeError(`${field}.${missingKey} is required`);
  }
};

const assertPlainObject = (value: unknown, field: string): void => {
  if (typeof value !== "object" || value === null || Array.isArray(value)) {
    throw new TypeError(`${field} must be an object`);
  }
  const prototype = Object.getPrototypeOf(value) as object | null;
  if (prototype !== Object.prototype && prototype !== null) {
    throw new TypeError(`${field} must be a plain object`);
  }
};

const compareStrings = (left: string, right: string): number =>
  left < right ? -1 : left > right ? 1 : 0;

export interface Ghost<TRuntimeSettings> {
  agentId: AgentId;
  actorId?: ActorId;
  tenantId: string;
  revision: string;
  /**
   * The revision of the last Runtime or placement change; later revisions
   * changed only the profile, which a running Runtime adopts in place
   * from its next claim. Absent, every revision changes the Runtime.
   */
  runtimeRevision?: string;
  agent: AgentDefinition;
  runtime: TRuntimeSettings;
  resources: GhostResources;
  /** TeamHub has a Runtime permission judge; absent, no Run reviews. */
  permissionReview?: true;
}

export type GhostInput<TRuntimeSettings> = Omit<
  Ghost<TRuntimeSettings>,
  "resources"
> & {
  resources?: GhostResourcesInput;
};

export type GhostRegistration<TRuntimeSettings> = Omit<
  GhostInput<TRuntimeSettings>,
  "agentId" | "actorId"
>;

export interface AgentUpdate<TRuntimeSettings> {
  expectedRevision: string;
  revision: string;
  agent: AgentDefinition;
  runtime: TRuntimeSettings;
  resources: GhostResourcesInput;
}

/** Cleanup identity is never an activatable Ghost or a native Session. */
export interface AgentDeletionIdentity<TRuntimeSettings> {
  readonly agentId: AgentId;
  readonly actorId: ActorId;
  readonly tenantId: string;
  readonly runtime: TRuntimeSettings;
  readonly contextRefs: readonly Readonly<ExecutionContextRef>[];
}

export type GhostReadFailureHandler = (
  agentId: AgentId,
  error: unknown,
) => void;

export interface GhostStore<TRuntimeSettings> {
  getDeletionIdentity?(
    agentId: AgentId,
  ): Promise<AgentDeletionIdentity<TRuntimeSettings> | null>;
  /** Only concurrent cold creations may share a pending read; no completed cache. */
  refresh?(
    agentId: AgentId,
    options?: {
      readonly shareInFlight: boolean;
    },
  ): Promise<void | {
    readonly revision: string;
    readonly activationReady: boolean;
  }>;
  /** Validate a replacement against durable authority without mutating the cache. */
  isReplacementCurrent?(
    agentId: AgentId,
    ghost: Ghost<TRuntimeSettings>,
  ): Promise<boolean>;
  /** Fresh authority check; cached configuration is not activation permission. */
  isActivationReady?(agentId: AgentId, revision: string): Promise<boolean>;
  insert(
    ghost: GhostInput<TRuntimeSettings>,
  ): Promise<"inserted" | "agent_id_conflict">;
  get(agentId: AgentId): Promise<Readonly<Ghost<TRuntimeSettings>> | null>;
  /** Recovery may collect per-Agent failures; ordinary inventory stays strict. */
  list(
    signal?: AbortSignal,
    onReadFailure?: GhostReadFailureHandler,
  ): Promise<readonly Readonly<Ghost<TRuntimeSettings>>[]>;
  setActorId(
    agentId: AgentId,
    actorId: ActorId,
  ): Promise<"updated" | "not_found">;
  replace?(
    agentId: AgentId,
    expectedRevision: string,
    ghost: Ghost<TRuntimeSettings>,
  ): Promise<"updated" | "not_found" | "revision_conflict">;
  remove(agentId: AgentId): Promise<"removed" | "not_found">;
  close(): Promise<void>;
}

export const snapshotGhost = <TRuntimeSettings>(
  ghost: GhostInput<TRuntimeSettings>,
): Readonly<Ghost<TRuntimeSettings>> => {
  if (!isProtocolId(ghost.tenantId)) {
    throw new TypeError("tenantId must be a valid protocol ID");
  }
  if (
    ghost.actorId !== undefined &&
    (typeof ghost.actorId !== "string" || ghost.actorId.length === 0)
  ) {
    throw new TypeError("actorId must be a non-empty string");
  }
  const canonicalGhost: Ghost<TRuntimeSettings> = {
    ...ghost,
    resources: materializeGhostResources(ghost.resources),
  };
  return snapshotValue(canonicalGhost, new WeakMap()) as Readonly<
    Ghost<TRuntimeSettings>
  >;
};

const isProtocolId = (value: unknown): value is string =>
  typeof value === "string" &&
  value.length <= 64 &&
  /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(value);

const snapshotValue = (
  value: unknown,
  snapshots: WeakMap<object, unknown>,
): unknown => {
  if (typeof value !== "object" || value === null) {
    return value;
  }

  const existing = snapshots.get(value);
  if (existing !== undefined) {
    return existing;
  }

  if (Array.isArray(value)) {
    const snapshot: unknown[] = [];
    snapshots.set(value, snapshot);
    for (const entry of value) {
      snapshot.push(snapshotValue(entry, snapshots));
    }
    return Object.freeze(snapshot);
  }

  const prototype = Object.getPrototypeOf(value) as object | null;
  if (prototype !== Object.prototype && prototype !== null) {
    throw new TypeError(
      "Ghost configuration must contain only plain objects, arrays, primitives, and functions",
    );
  }

  const snapshot = Object.create(prototype) as Record<string, unknown>;
  snapshots.set(value, snapshot);
  for (const [key, entry] of Object.entries(value)) {
    snapshot[key] = snapshotValue(entry, snapshots);
  }
  return Object.freeze(snapshot);
};