agl 1.0.17 → 21.0.2

package/ts/classes.controllermanagement.ts

@@ -0,0 +1,330 @@
+import * as plugins from './plugins.js';
+import {
+  controllerPackageName,
+  type IControllerStatus,
+  type IReq_ControllerStatus,
+  type IReq_ControllerUpgradeLaunch,
+  type IReq_ControllerUpgradePrepareBegin,
+  type IReq_ControllerUpgradeFinalize,
+} from '../ts_interfaces/index.js';
+import {
+  inspectControllerProcess,
+  signalVerifiedControllerProcess,
+} from './classes.processinspection.js';
+
+const currentCliName = String(controllerPackageName) === 'agl' ? 'agl' : 'hcon';
+const currentRuntimeName = currentCliName === 'agl' ? 'AGL' : currentCliName;
+
+export interface IControllerStatusExpectation {
+  packageName: string;
+  packageVersion: string;
+  protocolVersion?: number;
+  upgradeManagementVersion: number;
+}
+
+const harnessStates = ['starting', 'ready', 'stopping', 'stopped', 'failed'] as const;
+export const controllerUpgradePrepareBeginRequestTimeoutMs = 30_000;
+
+const isControllerHarnessStatus = (statusArg: unknown): boolean => {
+  if (typeof statusArg !== 'object' || statusArg === null) return false;
+  const status = statusArg as Record<string, unknown>;
+  return (
+    (status.harnessId === 'opencode' || status.harnessId === 'flex')
+    && harnessStates.some((stateArg) => status.state === stateArg)
+    && typeof status.healthy === 'boolean'
+    && (status.pid === undefined || Number.isSafeInteger(status.pid))
+    && (status.version === undefined || typeof status.version === 'string')
+  );
+};
+
+const isControllerUpgradeStatus = (statusArg: unknown): boolean => {
+  if (!statusArg || typeof statusArg !== 'object' || Array.isArray(statusArg)) return false;
+  const status = statusArg as Record<string, unknown>;
+  return Object.keys(status).length === 3
+    && typeof status.fromVersion === 'string'
+    && status.fromVersion.length > 0
+    && Buffer.byteLength(status.fromVersion, 'utf8') <= 128
+    && typeof status.toVersion === 'string'
+    && status.toVersion.length > 0
+    && Buffer.byteLength(status.toVersion, 'utf8') <= 128
+    && typeof status.phase === 'string'
+    && ['preparing', 'pausing', 'installing', 'restarting', 'continuing', 'completed', 'failed']
+      .includes(status.phase);
+};
+
+export const assertControllerStatus = (
+  statusArg: unknown,
+  expectationArg: IControllerStatusExpectation,
+): IControllerStatus => {
+  if (typeof statusArg !== 'object' || statusArg === null) {
+    throw new Error(`The service on the management port is not an ${currentRuntimeName} endpoint.`);
+  }
+  const status = statusArg as Partial<IControllerStatus>;
+  const harnesses = Array.isArray(status.harnesses) ? status.harnesses : [];
+  const openCode = harnesses.find((entryArg) => entryArg?.harnessId === 'opencode');
+  const flex = harnesses.find((entryArg) => entryArg?.harnessId === 'flex');
+  if (
+    status.packageName !== expectationArg.packageName
+    || status.packageVersion !== expectationArg.packageVersion
+    || (expectationArg.protocolVersion !== undefined
+      && status.protocolVersion !== expectationArg.protocolVersion)
+    || status.upgradeManagementVersion !== expectationArg.upgradeManagementVersion
+    || !Number.isSafeInteger(status.controllerPid)
+    || !Number.isSafeInteger(status.processGroupId)
+    || typeof status.processFingerprint !== 'string'
+    || status.processFingerprint.length < 8
+    || status.processFingerprint.length > 256
+    || (status.processMode !== 'detached' && status.processMode !== 'foreground')
+    || (status.lifecycleState !== 'starting'
+      && status.lifecycleState !== 'ready'
+      && status.lifecycleState !== 'stopping'
+      && status.lifecycleState !== 'stopped')
+    || typeof status.startedAt !== 'number'
+    || typeof status.setupRequired !== 'boolean'
+    || (status.upgrade !== undefined && !isControllerUpgradeStatus(status.upgrade))
+    || harnesses.length !== 2
+    || !openCode
+    || !flex
+    || !harnesses.every((entryArg) => isControllerHarnessStatus(entryArg))
+  ) {
+    throw new Error('The service on the management port has an incompatible controller identity.');
+  }
+  return status as IControllerStatus;
+};
+
+export const requestControllerUpgradePrepareBegin = async (
+  portArg: number,
+  tokenArg: string,
+  targetVersionArg: string,
+  gracePeriodMsArg: number,
+): Promise<IReq_ControllerUpgradePrepareBegin['response']> => {
+  const abortController = new AbortController();
+  const timeout = setTimeout(
+    () => abortController.abort(),
+    controllerUpgradePrepareBeginRequestTimeoutMs,
+  );
+  let socket: plugins.typedsocket.TypedSocket | undefined;
+  try {
+    socket = await plugins.typedsocket.TypedSocket.createClient(
+      new plugins.typedrequest.TypedRouter(),
+      `http://127.0.0.1:${portArg}`,
+      {
+        autoReconnect: false,
+        maxRetries: 0,
+        abortSignal: abortController.signal,
+      },
+    );
+    const response = await socket.createTypedRequest<IReq_ControllerUpgradePrepareBegin>(
+      'controller.upgrade.prepare.begin',
+      undefined,
+      {
+        timeoutMs: controllerUpgradePrepareBeginRequestTimeoutMs,
+        abortSignal: abortController.signal,
+      },
+    ).fire({ token: tokenArg, targetVersion: targetVersionArg, gracePeriodMs: gracePeriodMsArg });
+    if (
+      !response
+      || typeof response !== 'object'
+      || Array.isArray(response)
+      || Object.keys(response).length !== 1
+      || response.accepted !== true
+    ) throw new Error('The controller returned an invalid upgrade preparation response.');
+    return response;
+  } finally {
+    clearTimeout(timeout);
+    await socket?.stop();
+  }
+};
+
+export const requestControllerUpgradeFinalize = async (
+  portArg: number,
+  tokenArg: string,
+  modeArg: IReq_ControllerUpgradeFinalize['request']['mode'],
+  timeoutMsArg = 60_000,
+): Promise<IReq_ControllerUpgradeFinalize['response']> => {
+  const socket = await plugins.typedsocket.TypedSocket.createClient(
+    new plugins.typedrequest.TypedRouter(),
+    `http://127.0.0.1:${portArg}`,
+    { autoReconnect: false, maxRetries: 0 },
+  );
+  try {
+    return await socket.createTypedRequest<IReq_ControllerUpgradeFinalize>(
+      'controller.upgrade.finalize',
+      undefined,
+      { timeoutMs: timeoutMsArg },
+    ).fire({ token: tokenArg, mode: modeArg });
+  } finally {
+    await socket.stop();
+  }
+};
+
+export const queryControllerStatus = async (
+  portArg: number,
+  expectationArg: IControllerStatusExpectation,
+  timeoutMsArg = 2_500,
+): Promise<IControllerStatus> => {
+  const abortController = new AbortController();
+  const timeout = setTimeout(() => abortController.abort(), timeoutMsArg);
+  let socket: plugins.typedsocket.TypedSocket | undefined;
+  try {
+    const router = new plugins.typedrequest.TypedRouter();
+    socket = await plugins.typedsocket.TypedSocket.createClient(
+      router,
+      `http://127.0.0.1:${portArg}`,
+      {
+        autoReconnect: false,
+        maxRetries: 0,
+        abortSignal: abortController.signal,
+      },
+    );
+    const request = socket.createTypedRequest<IReq_ControllerStatus>(
+      'controller.status',
+      undefined,
+      { timeoutMs: timeoutMsArg, abortSignal: abortController.signal },
+    );
+    return assertControllerStatus(await request.fire({}), expectationArg);
+  } finally {
+    clearTimeout(timeout);
+    await socket?.stop();
+  }
+};
+
+export const tryQueryControllerStatus = async (
+  portArg: number,
+  expectationArg: IControllerStatusExpectation,
+): Promise<IControllerStatus | undefined> => {
+  try {
+    return await queryControllerStatus(portArg, expectationArg);
+  } catch {
+    return undefined;
+  }
+};
+
+export const isLoopbackPortListening = async (
+  portArg: number,
+  timeoutMsArg = 500,
+): Promise<boolean> => {
+  return await new Promise<boolean>((resolve) => {
+    const socket = plugins.net.createConnection({ host: '127.0.0.1', port: portArg });
+    let settled = false;
+    const finish = (resultArg: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      socket.destroy();
+      resolve(resultArg);
+    };
+    const timeout = setTimeout(() => finish(false), timeoutMsArg);
+    socket.once('connect', () => finish(true));
+    socket.once('error', () => finish(false));
+  });
+};
+
+export const requestControllerUpgradeLaunch = async (
+  portArg: number,
+  tokenArg: string,
+  timeoutMsArg = 15_000,
+): Promise<IReq_ControllerUpgradeLaunch['response']> => {
+  const abortController = new AbortController();
+  const timeout = setTimeout(() => abortController.abort(), timeoutMsArg);
+  let socket: plugins.typedsocket.TypedSocket | undefined;
+  try {
+    const router = new plugins.typedrequest.TypedRouter();
+    socket = await plugins.typedsocket.TypedSocket.createClient(
+      router,
+      `http://127.0.0.1:${portArg}`,
+      {
+        autoReconnect: false,
+        maxRetries: 0,
+        abortSignal: abortController.signal,
+      },
+    );
+    const response = await socket.createTypedRequest<IReq_ControllerUpgradeLaunch>(
+      'controller.upgrade.launch',
+      undefined,
+      { timeoutMs: timeoutMsArg, abortSignal: abortController.signal },
+    ).fire({ token: tokenArg });
+    if (
+      !response
+      || typeof response !== 'object'
+      || response.accepted !== true
+      || !Number.isSafeInteger(response.workerPid)
+      || response.workerPid < 2
+      || typeof response.logFilePath !== 'string'
+      || !plugins.path.isAbsolute(response.logFilePath)
+    ) {
+      throw new Error(`The controller returned an invalid ${currentCliName} upgrade launch response.`);
+    }
+    return response;
+  } finally {
+    clearTimeout(timeout);
+    await socket?.stop();
+  }
+};
+
+export const waitUntilControllerExited = async (
+  optionsArg: {
+    pid: number;
+    cliPath: string;
+    port: number;
+    expectedProcessGroupId: number;
+    expectedFingerprint: string;
+    command: '__serve' | 'foreground';
+  },
+  timeoutMsArg: number,
+): Promise<boolean> => {
+  const deadline = Date.now() + timeoutMsArg;
+  while (Date.now() < deadline) {
+    if (!await inspectControllerProcess(optionsArg)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 150));
+  }
+  return !await inspectControllerProcess(optionsArg);
+};
+
+export const resolveControllerStopSignal = (
+  statusArg: IControllerStatus,
+  phaseArg: 'cooperative' | 'hard',
+): { signal: NodeJS.Signals; signalProcessGroup: boolean } => {
+  if (phaseArg === 'cooperative') {
+    return { signal: 'SIGTERM', signalProcessGroup: false };
+  }
+  const signalProcessGroup = statusArg.processMode === 'detached';
+  if (signalProcessGroup && statusArg.processGroupId !== statusArg.controllerPid) {
+    throw new Error('The detached controller is not the verified leader of its process group.');
+  }
+  return { signal: 'SIGKILL', signalProcessGroup };
+};
+
+export const stopVerifiedController = async (optionsArg: {
+  status: IControllerStatus;
+  cliPath: string;
+  port: number;
+}): Promise<void> => {
+  const command: '__serve' | 'foreground' = optionsArg.status.processMode === 'detached'
+    ? '__serve'
+    : 'foreground';
+  const processIdentity = {
+    pid: optionsArg.status.controllerPid,
+    cliPath: optionsArg.cliPath,
+    port: optionsArg.port,
+    expectedProcessGroupId: optionsArg.status.processGroupId,
+    expectedFingerprint: optionsArg.status.processFingerprint,
+    command,
+  };
+  const cooperativeSignal = resolveControllerStopSignal(optionsArg.status, 'cooperative');
+  await signalVerifiedControllerProcess({
+    ...processIdentity,
+    ...cooperativeSignal,
+  });
+  if (await waitUntilControllerExited(processIdentity, 30_000)) return;
+  const hardSignal = resolveControllerStopSignal(optionsArg.status, 'hard');
+  await signalVerifiedControllerProcess({
+    ...processIdentity,
+    ...hardSignal,
+  });
+  if (!await waitUntilControllerExited(processIdentity, 15_000)) {
+    throw new Error(
+      'The exact controller process survived verified hard-stop escalation.',
+    );
+  }
+};

package/ts/classes.draftmanager.ts

@@ -0,0 +1,232 @@
+import {
+  controllerMaxDraftAttachmentBytes,
+  controllerMaxDraftAttachmentTotalBytes,
+  controllerMaxDraftAttachments,
+  controllerMaxDraftTextBytes,
+  type IControllerDraftAttachment,
+  type IControllerSessionDraft,
+  type IControllerSessionDraftUpdate,
+} from '../ts_interfaces/interfaces.js';
+
+const maximumDraftIdentities = 4_096;
+const maximumNonEmptyDrafts = 512;
+const maximumAggregateAttachmentBytes = 64 * 1024 * 1024;
+
+export class ControllerDraftConflictError extends Error {
+  constructor(public readonly draft: IControllerSessionDraft) {
+    super('The composer draft changed concurrently.');
+    this.name = 'ControllerDraftConflictError';
+  }
+}
+
+export class ControllerDraftLimitError extends Error {
+  constructor(messageArg: string) {
+    super(messageArg);
+    this.name = 'ControllerDraftLimitError';
+  }
+}
+
+export interface IControllerDraftMutationResult {
+  draft: IControllerSessionDraft;
+  update?: IControllerSessionDraftUpdate;
+}
+
+const cloneAttachment = (
+  attachmentArg: IControllerDraftAttachment,
+): IControllerDraftAttachment => ({ ...attachmentArg });
+
+const cloneDraft = (draftArg: IControllerSessionDraft): IControllerSessionDraft => ({
+  text: draftArg.text,
+  attachments: draftArg.attachments.map(cloneAttachment),
+  revision: draftArg.revision,
+});
+
+const emptyDraft = (): IControllerSessionDraft => ({ text: '', attachments: [], revision: 0 });
+
+const attachmentBytes = (draftArg: IControllerSessionDraft): number => (
+  draftArg.attachments.reduce((sum, attachment) => sum + attachment.size, 0)
+);
+
+const isNonEmpty = (draftArg: IControllerSessionDraft): boolean => (
+  draftArg.text.length > 0 || draftArg.attachments.length > 0
+);
+
+const attachmentsEqual = (
+  leftArg: readonly IControllerDraftAttachment[],
+  rightArg: readonly IControllerDraftAttachment[],
+): boolean => leftArg.length === rightArg.length && leftArg.every((left, index) => {
+  const right = rightArg[index];
+  return right !== undefined
+    && left.id === right.id
+    && left.name === right.name
+    && left.mediaType === right.mediaType
+    && left.size === right.size
+    && left.kind === right.kind
+    && left.dataBase64 === right.dataBase64;
+});
+
+export class ControllerDraftManager {
+  private readonly drafts = new Map<string, IControllerSessionDraft>();
+  private nonEmptyDrafts = 0;
+  private aggregateAttachmentBytes = 0;
+
+  public get(keyArg: string): IControllerSessionDraft {
+    return cloneDraft(this.drafts.get(keyArg) ?? emptyDraft());
+  }
+
+  public update(
+    keyArg: string,
+    expectedRevisionArg: number,
+    patchArg: { text?: string; attachments?: readonly IControllerDraftAttachment[] },
+  ): IControllerDraftMutationResult {
+    const current = this.drafts.get(keyArg) ?? emptyDraft();
+    if (current.revision !== expectedRevisionArg) {
+      throw new ControllerDraftConflictError(cloneDraft(current));
+    }
+    if (patchArg.text === undefined && patchArg.attachments === undefined) {
+      throw new Error('A draft update must replace text, attachments, or both.');
+    }
+
+    const nextText = patchArg.text ?? current.text;
+    const nextAttachments = patchArg.attachments === undefined
+      ? current.attachments
+      : patchArg.attachments.map(cloneAttachment);
+    this.assertDraftFields(nextText, nextAttachments);
+    const textChanged = nextText !== current.text;
+    const attachmentsChanged = !attachmentsEqual(nextAttachments, current.attachments);
+    if (!textChanged && !attachmentsChanged) return { draft: cloneDraft(current) };
+    if (current.revision >= Number.MAX_SAFE_INTEGER) {
+      throw new ControllerDraftLimitError('The draft revision limit was reached.');
+    }
+
+    const next: IControllerSessionDraft = {
+      text: nextText,
+      attachments: nextAttachments,
+      revision: current.revision + 1,
+    };
+    this.assertAdmission(keyArg, current, next);
+    this.store(keyArg, current, next);
+    return {
+      draft: cloneDraft(next),
+      update: {
+        revision: next.revision,
+        ...(textChanged ? { text: next.text } : {}),
+        ...(attachmentsChanged
+          ? { attachments: next.attachments.map(cloneAttachment) }
+          : {}),
+      },
+    };
+  }
+
+  public snapshot(keyArg: string, revisionArg: number): IControllerSessionDraft {
+    const current = this.drafts.get(keyArg) ?? emptyDraft();
+    if (current.revision !== revisionArg) {
+      throw new ControllerDraftConflictError(cloneDraft(current));
+    }
+    if (current.revision >= Number.MAX_SAFE_INTEGER) {
+      throw new ControllerDraftLimitError('The draft revision limit was reached.');
+    }
+    if (!current.text.trim()) throw new Error('The composer draft text must not be blank.');
+    return cloneDraft(current);
+  }
+
+  public clearExact(
+    keyArg: string,
+    revisionArg: number,
+  ): IControllerDraftMutationResult {
+    const current = this.drafts.get(keyArg);
+    if (!current || current.revision !== revisionArg) {
+      return { draft: cloneDraft(current ?? emptyDraft()) };
+    }
+    if (current.revision >= Number.MAX_SAFE_INTEGER) {
+      throw new ControllerDraftLimitError('The draft revision limit was reached.');
+    }
+    const next: IControllerSessionDraft = {
+      text: '',
+      attachments: [],
+      revision: current.revision + 1,
+    };
+    this.store(keyArg, current, next);
+    return {
+      draft: cloneDraft(next),
+      update: { revision: next.revision, text: '', attachments: [] },
+    };
+  }
+
+  public purge(keyArg: string): void {
+    const current = this.drafts.get(keyArg);
+    if (!current) return;
+    this.drafts.delete(keyArg);
+    if (isNonEmpty(current)) this.nonEmptyDrafts -= 1;
+    this.aggregateAttachmentBytes -= attachmentBytes(current);
+  }
+
+  public purgePrefix(prefixArg: string): void {
+    for (const key of this.drafts.keys()) {
+      if (key.startsWith(prefixArg)) this.purge(key);
+    }
+  }
+
+  public clear(): void {
+    this.drafts.clear();
+    this.nonEmptyDrafts = 0;
+    this.aggregateAttachmentBytes = 0;
+  }
+
+  private assertDraftFields(
+    textArg: string,
+    attachmentsArg: readonly IControllerDraftAttachment[],
+  ): void {
+    if (Buffer.byteLength(textArg, 'utf8') > controllerMaxDraftTextBytes) {
+      throw new ControllerDraftLimitError('The draft text exceeds the controller byte limit.');
+    }
+    if (attachmentsArg.length > controllerMaxDraftAttachments) {
+      throw new ControllerDraftLimitError('The draft attachment count exceeds the controller limit.');
+    }
+    const ids = new Set<string>();
+    let bytes = 0;
+    for (const attachment of attachmentsArg) {
+      if (ids.has(attachment.id)) throw new Error('Draft attachment IDs must be unique.');
+      ids.add(attachment.id);
+      if (attachment.size > controllerMaxDraftAttachmentBytes) {
+        throw new ControllerDraftLimitError('A draft attachment exceeds the controller byte limit.');
+      }
+      bytes += attachment.size;
+    }
+    if (bytes > controllerMaxDraftAttachmentTotalBytes) {
+      throw new ControllerDraftLimitError('The draft attachments exceed the controller total byte limit.');
+    }
+  }
+
+  private assertAdmission(
+    keyArg: string,
+    currentArg: IControllerSessionDraft,
+    nextArg: IControllerSessionDraft,
+  ): void {
+    if (!this.drafts.has(keyArg) && this.drafts.size >= maximumDraftIdentities) {
+      throw new ControllerDraftLimitError('The controller draft identity limit is exhausted.');
+    }
+    const nextNonEmptyCount = this.nonEmptyDrafts
+      - (isNonEmpty(currentArg) ? 1 : 0)
+      + (isNonEmpty(nextArg) ? 1 : 0);
+    if (nextNonEmptyCount > maximumNonEmptyDrafts) {
+      throw new ControllerDraftLimitError('The controller non-empty draft limit is exhausted.');
+    }
+    const nextAttachmentBytes = this.aggregateAttachmentBytes
+      - attachmentBytes(currentArg)
+      + attachmentBytes(nextArg);
+    if (nextAttachmentBytes > maximumAggregateAttachmentBytes) {
+      throw new ControllerDraftLimitError('The controller draft attachment memory limit is exhausted.');
+    }
+  }
+
+  private store(
+    keyArg: string,
+    currentArg: IControllerSessionDraft,
+    nextArg: IControllerSessionDraft,
+  ): void {
+    this.nonEmptyDrafts += (isNonEmpty(nextArg) ? 1 : 0) - (isNonEmpty(currentArg) ? 1 : 0);
+    this.aggregateAttachmentBytes += attachmentBytes(nextArg) - attachmentBytes(currentArg);
+    this.drafts.set(keyArg, nextArg);
+  }
+}