agl 1.0.17 → 21.0.2

package/ts/interfaces.gitreversion.ts

@@ -0,0 +1,336 @@
+import type * as plugins from './plugins.js';
+import type { IControllerFilesystemIdentity } from './interfaces.projects.js';
+
+export type TGitReversionDirection = 'undo' | 'redo';
+export type TGitReversionSideName = 'before' | 'after';
+export type TGitReversionWalPhase =
+  | 'intent'
+  | 'preflighted'
+  | 'applying'
+  | 'targetVerified'
+  | 'decision'
+  | 'committed'
+  | 'compensating'
+  | 'compensated'
+  | 'fenced';
+export type TGitReversionWorktreeState =
+  | 'intent'
+  | 'created'
+  | 'registered'
+  | 'active'
+  | 'removing'
+  | 'retainedDirty'
+  | 'removed'
+  | 'fenced';
+export type TGitReversionFaultPoint =
+  | 'intent.before-fsync'
+  | 'intent.after-fsync'
+  | 'intent.before-ref-cas'
+  | 'intent.after-ref-cas'
+  | 'intent.before-commit-fsync'
+  | 'intent.after-commit-fsync'
+  | 'intent.before-remove'
+  | 'intent.after-remove'
+  | 'atomic.after-rename-before-directory-fsync'
+  | 'capture.after-before-scan'
+  | 'capture.before-finalize-record'
+  | 'capture.after-finalize-record-fsync'
+  | 'capture.after-staging-repository'
+  | 'capture.after-intent-repository'
+  | 'capture.after-state-repository'
+  | 'capture.after-manifest-repository'
+  | 'capture.before-store-create'
+  | 'capture.after-store-create'
+  | 'capture.before-generation-enrollment'
+  | 'capture.after-generation-enrollment'
+  | 'capture.after-publication-fsync'
+  | 'capture.before-root-delete'
+  | 'capture.after-root-delete'
+  | 'capture.after-root-delete-fsync'
+  | 'apply.after-intent'
+  | 'apply.after-preflight'
+  | 'apply.after-source-pack-import'
+  | 'apply.after-source-pack-fsync'
+  | 'apply.after-repository'
+  | 'apply.after-target-verification'
+  | 'apply.after-decision-repository'
+  | 'apply.after-decision'
+  | 'apply.after-state-repository'
+  | 'apply.during-compensation'
+  | 'apply.before-source-keep-remove'
+  | 'apply.after-source-keep-quarantine'
+  | 'apply.after-source-keep-remove'
+  | 'apply.after-source-keep-remove-fsync'
+  | 'worktree.after-intent'
+  | 'worktree.after-create'
+  | 'worktree.after-removed-record'
+  | 'worktree.record-read.after-open'
+  | 'index.before-sidecar-fsync'
+  | 'index.after-sidecar-fsync'
+  | 'index.after-link'
+  | 'index.after-link-fsync'
+  | 'index.after-rename'
+  | 'index.after-rename-fsync'
+  | 'index.after-cleanup'
+  | 'index.after-cleanup-fsync';
+
+export type TGitReversionReference = {
+  schemaVersion: 1;
+  captureKey: string;
+  manifestId: string;
+};
+
+export type TGitReversionFinalizedOutcome =
+  plugins.flexharness.TFlexTurnReversionFinalizedOutcome;
+export type TGitReversionCaptureInspection =
+  plugins.flexharness.TFlexTurnReversionCaptureInspectionV2;
+export type TGitReversionApplyInspection =
+  plugins.flexharness.IFlexTurnReversionApplyInspection;
+
+export interface IGitReversionIdentity {
+  projectId: string;
+  sessionId: string;
+  runId: string;
+  captureId: string;
+}
+
+export interface IGitReversionCaptureRequest extends IGitReversionIdentity {
+  signal?: AbortSignal;
+}
+
+export interface IGitReversionApplyRequest {
+  identity: IGitReversionIdentity;
+  reference: TGitReversionReference;
+  operationId: string;
+  direction: TGitReversionDirection;
+  signal?: AbortSignal;
+}
+
+export interface IGitReversionReleaseRequest {
+  identity: IGitReversionIdentity;
+  reference: TGitReversionReference;
+  signal?: AbortSignal;
+}
+
+export interface IGitReversionMetadataRequest {
+  identity: IGitReversionIdentity;
+  reference: TGitReversionReference;
+  signal?: AbortSignal;
+}
+
+export interface IGitReversionWorktreeRequest {
+  projectId: string;
+  sessionId: string;
+  signal?: AbortSignal;
+}
+
+export interface IGitReversionWorktreeRemoveRequest extends IGitReversionWorktreeRequest {
+  worktreeId: string;
+}
+
+export interface IGitReversionLimits {
+  maximumProjects: number;
+  maximumRepositories: number;
+  maximumScannedDirectories: number;
+  maximumScanDepth: number;
+  maximumPaths: number;
+  maximumPathBytes: number;
+  maximumMetadataBytes: number;
+  maximumPrivateRefs: number;
+  maximumPrivateMetadataAggregateBytes: number;
+  maximumIntentFiles: number;
+  maximumIntentEntries: number;
+  maximumIntentFileBytes: number;
+  maximumIntentAggregateBytes: number;
+  maximumScavengeEntries: number;
+  maximumIgnorePolicyFiles: number;
+  maximumIgnorePolicyBytes: number;
+  maximumWorktrees: number;
+  maximumCaptureRecords: number;
+  maximumCaptureRecordBytes: number;
+  maximumCaptureAggregateBytes: number;
+  maximumCaptures: number;
+  maximumGenerationsPerCapture: number;
+  maximumGenerationBytes: number;
+  maximumGenerationObjects: number;
+  maximumCaptureStoreBytes: number;
+  maximumCaptureStoreObjects: number;
+  maximumControllerStoreBytes: number;
+  maximumControllerStoreObjects: number;
+  maximumControllerGenerations: number;
+  maximumMetadataRecordsPerCapture: number;
+  maximumMetadataRecordBytes: number;
+  maximumMetadataAggregateBytes: number;
+  maximumLifecycleEntries: number;
+  maximumLifecycleRecordBytes: number;
+  maximumLifecycleAggregateBytes: number;
+  maximumPrivateRefsPerCapture: number;
+  commandTimeoutMs: number;
+  worktreeCommandTimeoutMs: number;
+  maximumCommandOutputBytes: number;
+  maximumConcurrentGitCommands: number;
+  maximumQueuedGitCommands: number;
+}
+
+export interface IGitReversionFaultContext {
+  point: TGitReversionFaultPoint;
+  captureKey?: string;
+  operationId?: string;
+  repositoryId?: string;
+  worktreeId?: string;
+  intentId?: string;
+  ref?: string;
+}
+
+export interface IGitReversionOptions {
+  ownerId: string;
+  /** This path must be exclusively owned by one live controller process. */
+  temporaryRoot?: string;
+  limits?: Partial<IGitReversionLimits>;
+  testOnlyFaultInjector?: (
+    context: IGitReversionFaultContext,
+  ) => Promise<void> | void;
+}
+
+export interface IGitReversionRepositoryIdentity {
+  scope: 'project' | 'owned-worktree';
+  repositoryId: string;
+  commonId: string;
+  objectFormat: 'sha1' | 'sha256';
+  root: string;
+  rootIdentity: IControllerFilesystemIdentity;
+  gitEntryPath: string;
+  gitEntryIdentity: IControllerFilesystemIdentity;
+  gitDir: string;
+  gitDirIdentity: IControllerFilesystemIdentity;
+  commonDir: string;
+  commonDirIdentity: IControllerFilesystemIdentity;
+  objectDir: string;
+  objectDirIdentity: IControllerFilesystemIdentity;
+  indexPath: string;
+  indexParentIdentity: IControllerFilesystemIdentity;
+  label: string;
+  excludedRepositoryPaths: string[];
+}
+
+export interface IGitReversionSide {
+  objectGenerationId?: string;
+  worktreeTree: string;
+  indexTree: string;
+  headOid: string;
+  headRef: string | null;
+  refs: Record<string, string>;
+  symbolicRefs: Record<string, string>;
+  topologyHash: string;
+  ignorePolicyHash: string;
+  operationHash: string;
+  unsupportedReason?: string;
+}
+
+export interface IGitReversionRepositoryCapture {
+  repository: IGitReversionRepositoryIdentity;
+  before: IGitReversionSide;
+  after?: IGitReversionSide;
+}
+
+export interface IGitReversionManifest {
+  schemaVersion: 1;
+  kind: 'manifest';
+  ownerKey: string;
+  captureKey: string;
+  identity: IGitReversionIdentity;
+  projectDirectory: string;
+  projectIdentity: IControllerFilesystemIdentity;
+  phase: 'prepared' | 'finalized';
+  repositories: IGitReversionRepositoryCapture[];
+  reasonCode?: string;
+  affectedWorkspaces: Array<{ id: string; label: string }>;
+}
+
+export interface IGitReversionCaptureState {
+  schemaVersion: 1;
+  kind: 'capture-state';
+  captureKey: string;
+  manifestId: string;
+  currentSide: TGitReversionSideName;
+  revision: number;
+  outcome: TGitReversionFinalizedOutcome;
+}
+
+export interface IGitReversionSourcePack {
+  generationId: string;
+  packHash: string;
+  packBytes: number;
+  objectCount: number;
+  syntheticRootOid: string;
+  keepToken: string;
+}
+
+export interface IGitReversionApplyPlan {
+  captureKey: string;
+  repository: IGitReversionRepositoryIdentity;
+  initial: IGitReversionSide;
+  source: IGitReversionSide;
+  target: IGitReversionSide;
+  desiredWorktreeTree: string;
+  desiredIndexTree: string;
+  scopedRefs: string[];
+  sourcePack: IGitReversionSourcePack;
+}
+
+export interface IGitReversionApplyWal {
+  schemaVersion: 1;
+  kind: 'apply-wal';
+  captureKey: string;
+  manifestId: string;
+  operationId: string;
+  operationKey: string;
+  direction: TGitReversionDirection;
+  attempt: number;
+  sourceSide: TGitReversionSideName;
+  targetSide: TGitReversionSideName;
+  sourceRevision: number;
+  phase: TGitReversionWalPhase;
+  decision?: 'source' | 'target';
+  touchedRepositoryIds: string[];
+  plans: IGitReversionApplyPlan[];
+  generationIds: Record<string, string[]>;
+}
+
+export interface IGitReversionWorktreeDescriptor {
+  worktreeId: string;
+  projectId: string;
+  sessionId: string;
+  path: string;
+  repositoryId: string;
+  createdAt: string;
+  state: Exclude<TGitReversionWorktreeState, 'intent' | 'created' | 'registered' | 'removed'>;
+}
+
+export interface IGitReversionWorktreeRecord {
+  schemaVersion: 1;
+  kind: 'worktree';
+  ownerKey: string;
+  worktreeId: string;
+  projectId: string;
+  sessionId: string;
+  path: string;
+  parentPath: string;
+  parentIdentity: IControllerFilesystemIdentity;
+  pathIdentity?: IControllerFilesystemIdentity;
+  sourceRoot: string;
+  sourceCommonDir: string;
+  sourceRepository: IGitReversionRepositoryIdentity;
+  repositoryId: string;
+  createdAt: string;
+  state: TGitReversionWorktreeState;
+}
+
+export interface IGitReversionMetadata {
+  reference: TGitReversionReference;
+  disposition: TGitReversionFinalizedOutcome['disposition'];
+  currentSide: TGitReversionSideName;
+  revision: number;
+  affectedWorkspaces: Array<{ id: string; label: string }>;
+  reasonCode?: string;
+}

package/ts/interfaces.lifecycle.ts

@@ -0,0 +1,46 @@
+import type { IControllerStatus, TControllerProcessMode } from '../ts_interfaces/index.js';
+import type { IControllerRuntimeOverrides } from './interfaces.config.js';
+
+export interface IControllerStartOptions {
+  processMode: TControllerProcessMode;
+  runtimeOverrides: IControllerRuntimeOverrides;
+  /** Operator-provided first-start setup code; a random code is minted when absent. */
+  setupCode?: string;
+  /** Private upgrade transaction token received over parent IPC. */
+  upgradeToken?: string;
+  upgradeGlobalRoot?: string;
+  onStartupBlocked?: (errorArg: Error) => Promise<void>;
+}
+
+export interface IControllerStartResult {
+  status: IControllerStatus;
+  publicUrl: string;
+  setupCode?: string;
+}
+
+export interface IControllerReadyIpcMessage {
+  type: 'ready';
+  status: IControllerStatus;
+  publicUrl: string;
+  setupCode?: string;
+}
+
+export interface IControllerStartupErrorIpcMessage {
+  type: 'startupError';
+  message: string;
+  retained?: true;
+}
+
+export interface IControllerStartIpcMessage {
+  type: 'start';
+  /** Transported over IPC so the code never appears in the detached child's argv. */
+  setupCode?: string;
+  /** Transported over IPC so the token never appears in the detached child's argv. */
+  upgradeToken?: string;
+  upgradeGlobalRoot?: string;
+}
+
+export type TControllerIpcMessage =
+  | IControllerReadyIpcMessage
+  | IControllerStartupErrorIpcMessage
+  | IControllerStartIpcMessage;

package/ts/interfaces.opencode.ts

@@ -0,0 +1,153 @@
+import type * as plugins from './plugins.js';
+import type {
+  IControllerEvent,
+  IControllerMessage,
+  IControllerReasoningUpdate,
+  IControllerRuntimeId,
+  IControllerTextUpdate,
+  IControllerToolExecution,
+  TControllerHarnessLifecycleState,
+} from '../ts_interfaces/index.js';
+
+export const openCodeExpectedVersion = '1.18.15' as const;
+export const openCodeUsername = 'harness-controller' as const;
+
+export interface IOpenCodeHealth {
+  healthy: true;
+  version: typeof openCodeExpectedVersion;
+}
+
+export interface IOpenCodeLogEntry {
+  timestamp: number;
+  stream: 'stdout' | 'stderr';
+  line: string;
+  truncated: boolean;
+}
+
+export interface IOpenCodeSupervisorStatus {
+  state: TControllerHarnessLifecycleState;
+  healthy: boolean;
+  pid?: number;
+  version?: string;
+  startedAt?: number;
+}
+
+export interface IOpenCodeConnectionConfig {
+  baseUrl: string;
+  directory: string;
+  username: typeof openCodeUsername;
+  password: string;
+}
+
+export interface IOpenCodeProcessGroupController {
+  isAlive(processGroupIdArg: number): boolean | Promise<boolean>;
+  signal(
+    processGroupIdArg: number,
+    signalArg: 'SIGTERM' | 'SIGKILL',
+  ): void | Promise<void>;
+}
+
+export interface IOpenCodeSupervisorOptions {
+  directory: string;
+  port: number;
+  startupTimeoutMs?: number;
+  healthRequestTimeoutMs?: number;
+  healthPollIntervalMs?: number;
+  stopTimeoutMs?: number;
+  finalStopTimeoutMs?: number;
+  logEntryLimit?: number;
+  logLineByteLimit?: number;
+  spawnFactory?: typeof plugins.childProcess.spawn;
+  fetchImplementation?: typeof globalThis.fetch;
+  listenerOwnershipVerifier?: (
+    processId: number,
+    port: number
+  ) => boolean | Promise<boolean>;
+  processGroupController?: IOpenCodeProcessGroupController;
+  /** Called after the owned child exits and can no longer access operation resources. */
+  onChildExit?: () => void;
+}
+
+export type TOpenCodeSdkClient = ReturnType<typeof plugins.opencodeSdk.createOpencodeClient>;
+
+export interface IOpenCodeClientOptions extends IOpenCodeConnectionConfig {
+  clientFactory?: typeof plugins.opencodeSdk.createOpencodeClient;
+  fetchImplementation?: typeof globalThis.fetch;
+  /** Current-generation lease held until each non-streaming SDK response body settles. */
+  acquireRuntimeLease?: () => () => void;
+}
+
+/** Adapter-internal normalized entries derived from one OpenCode source message. */
+export interface IOpenCodeNormalizedMessageBundle {
+  sourceMessageId: IControllerRuntimeId;
+  structuralDigest: string;
+  sourceRole: 'user' | 'assistant';
+  parentMessageId?: IControllerRuntimeId;
+  terminal: boolean;
+  messages: IControllerMessage[];
+}
+
+export interface IOpenCodeMessageLifecycle {
+  sessionId: IControllerRuntimeId;
+  messageId: IControllerRuntimeId;
+  role: 'user' | 'assistant';
+  parentMessageId?: IControllerRuntimeId;
+  terminal: boolean;
+}
+
+/** Adapter-internal page shape; cursors remain opaque OpenCode values. */
+export interface IOpenCodeMessagePage {
+  bundles: IOpenCodeNormalizedMessageBundle[];
+  nextCursor?: string;
+}
+
+export type TOpenCodeToolExecution = Omit<
+  IControllerToolExecution,
+  'revision' | 'streamEpoch'
+>;
+
+export type TOpenCodeReasoningUpdate = Omit<
+  IControllerReasoningUpdate,
+  'order' | 'revision' | 'streamEpoch'
+>;
+
+export type TOpenCodeTextUpdate = Omit<
+  IControllerTextUpdate,
+  'order' | 'revision' | 'streamEpoch'
+>;
+
+export interface IOpenCodeEventStreamOptions {
+  /** directory is the raw project worktree the event belongs to. */
+  onEvent: (event: IControllerEvent, directory: string) => void | Promise<void>;
+  /** Replace-only tool snapshot; the controller assigns delivery ordering. */
+  onToolExecution?: (
+    execution: TOpenCodeToolExecution,
+    directory: string,
+    timestamp: number,
+  ) => void | Promise<void>;
+  /** Replace-only Assistant reasoning snapshot; the controller assigns ordering. */
+  onReasoningUpdate?: (
+    update: TOpenCodeReasoningUpdate,
+    directory: string,
+  ) => void | Promise<void>;
+  /** Replace-only Assistant text snapshot; the controller assigns ordering. */
+  onTextUpdate?: (
+    update: TOpenCodeTextUpdate,
+    directory: string,
+  ) => void | Promise<void>;
+  /** Exact source-message lifecycle used for controller-owned resource cleanup. */
+  onMessageLifecycle?: (
+    lifecycle: IOpenCodeMessageLifecycle,
+    directory: string,
+  ) => void | Promise<void>;
+  /** Fires in stream order for the initial connection and every SDK reconnect. */
+  onConnected?: () => void | Promise<void>;
+  /** Signals that live snapshots may have been lost or could not be normalized. */
+  onToolStreamGap?: () => void | Promise<void>;
+  /** Signals that live Assistant snapshots may have been lost or could not be normalized. */
+  onMessageStreamGap?: () => void | Promise<void>;
+  /** Signals that the shared SDK stream ended and both snapshot streams were lost. */
+  onStreamGap?: () => void | Promise<void>;
+  onError?: (error: Error) => void;
+  signal?: AbortSignal;
+}