@modelprofile.com/flexharness-agent 6.0.0

package/ts_agent/smartagent.transactions.ts

@@ -0,0 +1,193 @@
+import type {
+  IGenerationBegunEvent,
+  IGenerationExecutionCompletedEvent,
+  IGenerationExecutionStartedEvent,
+  IGenerationOutcomeEvent,
+  IToolExecutionIntentEvent,
+  TAgentControlEvent,
+  TAgentEvent,
+  TAgentGenerationOutcome,
+} from './smartagent.events.js';
+
+export type TAgentGenerationTransactionState =
+  | 'begun'
+  | 'execution-started'
+  | 'execution-completed'
+  | TAgentGenerationOutcome
+  | 'invalid';
+
+export interface IAgentGenerationTransaction {
+  generationId: string;
+  state: TAgentGenerationTransactionState;
+  begun: IGenerationBegunEvent;
+  executionStarted?: IGenerationExecutionStartedEvent;
+  executionCompleted?: IGenerationExecutionCompletedEvent;
+  outcome?: IGenerationOutcomeEvent;
+}
+
+const isControlEvent = (event: TAgentEvent): event is TAgentControlEvent =>
+  event.type === 'generation-begun'
+  || event.type === 'generation-execution-started'
+  || event.type === 'generation-execution-completed'
+  || event.type === 'generation-outcome'
+  || event.type === 'tool-execution-intent'
+  || event.type === 'tool-execution-reconciliation';
+
+export const getAgentGenerationTransactions = (
+  events: readonly TAgentEvent[],
+): Map<string, IAgentGenerationTransaction> => {
+  interface IAccumulatedTransaction {
+    begun?: IGenerationBegunEvent;
+    begunCount: number;
+    begunIndex: number;
+    started?: IGenerationExecutionStartedEvent;
+    startedCount: number;
+    startedIndex: number;
+    completed?: IGenerationExecutionCompletedEvent;
+    completedCount: number;
+    completedIndex: number;
+    outcome?: IGenerationOutcomeEvent;
+    outcomeCount: number;
+    outcomeIndex: number;
+  }
+  const accumulated = new Map<string, IAccumulatedTransaction>();
+  const entryFor = (generationId: string): IAccumulatedTransaction => {
+    let entry = accumulated.get(generationId);
+    if (!entry) {
+      entry = {
+        begunCount: 0,
+        begunIndex: -1,
+        startedCount: 0,
+        startedIndex: -1,
+        completedCount: 0,
+        completedIndex: -1,
+        outcomeCount: 0,
+        outcomeIndex: -1,
+      };
+      accumulated.set(generationId, entry);
+    }
+    return entry;
+  };
+  for (const [index, event] of events.entries()) {
+    if (event.type === 'generation-begun') {
+      const entry = entryFor(event.generationId);
+      entry.begun ??= event;
+      entry.begunCount++;
+      if (entry.begunIndex < 0) entry.begunIndex = index;
+    } else if (event.type === 'generation-execution-started') {
+      const entry = entryFor(event.generationId);
+      entry.started ??= event;
+      entry.startedCount++;
+      if (entry.startedIndex < 0) entry.startedIndex = index;
+    } else if (event.type === 'generation-execution-completed') {
+      const entry = entryFor(event.generationId);
+      entry.completed ??= event;
+      entry.completedCount++;
+      if (entry.completedIndex < 0) entry.completedIndex = index;
+    } else if (event.type === 'generation-outcome') {
+      const entry = entryFor(event.generationId);
+      entry.outcome ??= event;
+      entry.outcomeCount++;
+      if (entry.outcomeIndex < 0) entry.outcomeIndex = index;
+    }
+  }
+  const transactions = new Map<string, IAgentGenerationTransaction>();
+  for (const [generationId, entry] of accumulated) {
+    if (!entry.begun) continue;
+    let state: TAgentGenerationTransactionState;
+    if (
+      entry.begunCount !== 1
+      || entry.startedCount > 1
+      || entry.completedCount > 1
+      || entry.outcomeCount > 1
+      || (entry.startedIndex >= 0 && entry.startedIndex < entry.begunIndex)
+      || (entry.startedCount === 0 && entry.completedCount > 0)
+      || (entry.completedIndex >= 0 && entry.completedIndex < entry.startedIndex)
+      || (entry.outcomeIndex >= 0 && entry.outcomeIndex < entry.begunIndex)
+      || (entry.outcomeIndex >= 0 && entry.startedIndex > entry.outcomeIndex)
+      || (entry.outcomeIndex >= 0 && entry.completedIndex > entry.outcomeIndex)
+      || (
+        (entry.outcome?.outcome === 'accepted' || entry.outcome?.outcome === 'rejected')
+        && entry.completedCount === 0
+      )
+    ) {
+      state = 'invalid';
+    } else if (entry.outcome) {
+      state = entry.outcome.outcome;
+    } else if (entry.completed) {
+      state = 'execution-completed';
+    } else if (entry.started) {
+      state = 'execution-started';
+    } else {
+      state = 'begun';
+    }
+    transactions.set(generationId, {
+      generationId,
+      state,
+      begun: entry.begun,
+      executionStarted: entry.started,
+      executionCompleted: entry.completed,
+      outcome: entry.outcome,
+    });
+  }
+  return transactions;
+};
+
+export const isTransactionalGeneration = (
+  events: readonly TAgentEvent[],
+  generationId: string,
+): boolean => getAgentGenerationTransactions(events).has(generationId);
+
+export const filterModelVisibleAgentEvents = (
+  events: readonly TAgentEvent[],
+): TAgentEvent[] => {
+  const transactions = getAgentGenerationTransactions(events);
+  const visibleEvents: TAgentEvent[] = [];
+  for (const event of events) {
+    if (isControlEvent(event)) continue;
+    if (event.type === 'context-compaction' && event.archivedTransactions) {
+      visibleEvents.push({ ...event, archivedTransactions: undefined });
+      continue;
+    }
+    if (!event.generationId) {
+      visibleEvents.push(event);
+      continue;
+    }
+    const transaction = transactions.get(event.generationId);
+    if (
+      !transaction
+      || transaction.state === 'accepted'
+      || transaction.state === 'execution-started'
+    ) visibleEvents.push(event);
+  }
+  return visibleEvents;
+};
+
+export const getOpenAgentGenerationTransactions = (
+  events: readonly TAgentEvent[],
+): IAgentGenerationTransaction[] => [...getAgentGenerationTransactions(events).values()]
+  .filter((transaction) =>
+    transaction.state !== 'accepted'
+    && transaction.state !== 'rejected'
+    && transaction.state !== 'interrupted');
+
+export const getUncertainToolExecutionIntents = (
+  events: readonly TAgentEvent[],
+  generationId?: string,
+): IToolExecutionIntentEvent[] => {
+  const uncertain = new Map<string, IToolExecutionIntentEvent>();
+  for (const event of events) {
+    if (
+      event.type === 'tool-execution-intent'
+      && (generationId === undefined || event.generationId === generationId)
+    ) {
+      uncertain.set(event.id, event);
+    } else if (event.type === 'tool-result' && event.executionIntentId) {
+      const intent = uncertain.get(event.executionIntentId);
+      if (intent?.generationId === event.generationId) {
+        uncertain.delete(event.executionIntentId);
+      }
+    }
+  }
+  return [...uncertain.values()];
+};

package/ts_agent/tool.adapter.ts

@@ -0,0 +1,85 @@
+import type { IToolExecutionContext } from './tool.contracts.js';
+
+export interface IToolExecutionAdapterRequest {
+  /** Host-defined isolation kind, for example "sandbox" or "container". */
+  isolation: string;
+  sessionId?: string;
+  cwd?: string;
+  rootDir?: string;
+  abortSignal?: AbortSignal;
+  metadata?: Record<string, unknown>;
+}
+
+export interface IToolExecutionAdapter {
+  readonly id: string;
+  create(request: IToolExecutionAdapterRequest): Promise<IToolExecutionContext>;
+  destroy?(context: IToolExecutionContext): Promise<void>;
+}
+
+export interface IToolExecutionContextLease {
+  readonly adapterId: string;
+  readonly context: IToolExecutionContext;
+  close(): Promise<void>;
+}
+
+export class ToolExecutionAdapterCleanupError extends Error {
+  constructor(
+    public readonly adapter: IToolExecutionAdapter,
+    public readonly context: IToolExecutionContext,
+    public readonly abortReason: unknown,
+    public readonly cleanupError: unknown,
+  ) {
+    super(`Tool execution adapter "${adapter.id}" failed to clean up after acquisition was aborted.`);
+    this.name = 'ToolExecutionAdapterCleanupError';
+  }
+
+  public async retryCleanup(): Promise<void> {
+    await this.adapter.destroy?.(this.context);
+  }
+}
+
+export const acquireToolExecutionContext = async (
+  adapter: IToolExecutionAdapter,
+  request: IToolExecutionAdapterRequest,
+): Promise<IToolExecutionContextLease> => {
+  if (!adapter.id.trim()) throw new Error('Tool execution adapter id must not be empty.');
+  if (!request.isolation.trim()) throw new Error('Tool execution isolation must not be empty.');
+  request.abortSignal?.throwIfAborted();
+  const context = await adapter.create(request);
+  try {
+    request.abortSignal?.throwIfAborted();
+  } catch (abortReason) {
+    try {
+      await adapter.destroy?.(context);
+    } catch (cleanupError) {
+      throw new ToolExecutionAdapterCleanupError(
+        adapter,
+        context,
+        abortReason,
+        cleanupError,
+      );
+    }
+    throw abortReason;
+  }
+  let closed = false;
+  let closePromise: Promise<void> | undefined;
+  return {
+    adapterId: adapter.id,
+    context,
+    close: async () => {
+      if (closed) return;
+      if (!closePromise) {
+        closePromise = Promise.resolve()
+          .then(() => adapter.destroy?.(context))
+          .then(() => {
+            closed = true;
+          })
+          .catch((error) => {
+            closePromise = undefined;
+            throw error;
+          });
+      }
+      await closePromise;
+    },
+  };
+};

package/ts_agent/tool.contracts.ts

@@ -0,0 +1,149 @@
+export interface IToolPermissionRequest {
+  type: string;
+  title: string;
+  metadata?: Record<string, unknown>;
+  toolCallId?: string;
+  abortSignal?: AbortSignal;
+}
+
+export interface IToolInvocationOptions {
+  toolCallId?: string;
+  abortSignal?: AbortSignal;
+}
+
+export interface IToolRunOptions extends IToolInvocationOptions {
+  cwd?: string;
+  timeoutMs?: number;
+  /** Ordered process output. Implementations must await returned promises and abort on rejection. */
+  onOutput?: (stream: 'stdout' | 'stderr', chunk: string) => Promise<void> | void;
+}
+
+export interface IToolShellResult {
+  exitCode: number;
+  stdout: string;
+  stderr?: string;
+  signal?: string;
+}
+
+export interface IShellCommand {
+  executable: string;
+  args: string[];
+}
+
+export interface IToolShellContext {
+  run(command: string, options?: IToolRunOptions): Promise<IToolShellResult | string>;
+  /** Direct execution without shell parsing. Arguments are passed literally. */
+  runStructured?(command: IShellCommand, options?: IToolRunOptions): Promise<IToolShellResult | string>;
+}
+
+export interface IToolJobRequest {
+  type: 'shell' | string;
+  command?: IShellCommand;
+  cwd?: string;
+  timeoutMs?: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface IShellStartedResult {
+  executionId: string;
+  state: 'running';
+}
+
+export interface IShellFinishedResult {
+  executionId: string;
+  state: 'finished' | 'failed' | 'aborted';
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  signal?: string;
+}
+
+export interface IToolJobState {
+  executionId: string;
+  type: string;
+  state: 'running' | 'finished' | 'failed' | 'aborted';
+  request?: IToolJobRequest;
+  exitCode?: number | null;
+  stdout?: string;
+  stderr?: string;
+  signal?: string;
+  startedAt?: number;
+  updatedAt?: number;
+  finishedAt?: number;
+}
+
+export interface IToolJobHandle extends IShellStartedResult {
+  completion: Promise<IToolJobState>;
+}
+
+export interface IToolJobEvent {
+  type: 'started' | 'finished';
+  job: IToolJobState;
+}
+
+export interface IToolJobOutputEvent {
+  type: 'output';
+  job: IToolJobState;
+  stream: 'stdout' | 'stderr';
+  chunk: string;
+  sequence: number;
+}
+
+export type TToolJobEvent = IToolJobEvent | IToolJobOutputEvent;
+export type TToolJobEventListener = (event: TToolJobEvent) => void | Promise<void>;
+
+export interface IToolJobContext {
+  start(request: IToolJobRequest, invocationOptions?: IToolInvocationOptions): Promise<IToolJobHandle>;
+  get(executionId: string): Promise<IToolJobState>;
+  list(): Promise<IToolJobState[]>;
+  abort?(executionId: string): Promise<void>;
+  subscribe?(listener: TToolJobEventListener): () => void;
+}
+
+export interface IToolFilesystemReadOptions {
+  startLine?: number;
+  endLine?: number;
+}
+
+export interface IToolFilesystemListOptions {
+  recursive?: boolean;
+}
+
+export interface IToolFilesystemContext {
+  readFile(filePath: string, options?: IToolFilesystemReadOptions, invocationOptions?: IToolInvocationOptions): Promise<string>;
+  writeFile(filePath: string, content: string, invocationOptions?: IToolInvocationOptions): Promise<string | void>;
+  listDirectory(directoryPath: string, options?: IToolFilesystemListOptions, invocationOptions?: IToolInvocationOptions): Promise<string[] | string>;
+  deletePath?(targetPath: string, invocationOptions?: IToolInvocationOptions): Promise<string | void>;
+}
+
+export interface IToolBrowserRunOptions extends IToolInvocationOptions {
+  timeoutMs?: number;
+}
+
+export type TBrowserToolAction = 'navigate' | 'snapshot' | 'screenshot' | 'click' | 'fill' | 'press' | 'evaluate' | 'close';
+
+export interface IBrowserToolInput {
+  action?: TBrowserToolAction | string;
+  url?: string;
+  selector?: string;
+  text?: string;
+  script?: string;
+  timeoutMs?: number;
+}
+
+export interface IToolBrowserContext {
+  execute(input: IBrowserToolInput, options?: IToolBrowserRunOptions): Promise<unknown>;
+}
+
+export interface IToolExecutionContext {
+  cwd?: string;
+  rootDir?: string;
+  additionalReadOnlyRoots?: string[];
+  abortSignal?: AbortSignal;
+  shell?: IToolShellContext;
+  fs?: IToolFilesystemContext;
+  browser?: IToolBrowserContext;
+  jobs?: IToolJobContext;
+  requestPermission?: (request: IToolPermissionRequest) => Promise<void>;
+}
+

package/ts_agent/tool.persistence.ts

@@ -0,0 +1,64 @@
+import type { IToolJobState } from './tool.contracts.js';
+
+export const JOB_SNAPSHOT_SCHEMA_VERSION = 1 as const;
+
+export interface IToolJobSnapshot {
+  schemaVersion: typeof JOB_SNAPSHOT_SCHEMA_VERSION;
+  revision: number;
+  updatedAt: number;
+  jobs: IToolJobState[];
+}
+
+export interface IToolJobStore {
+  load(abortSignal?: AbortSignal): Promise<IToolJobSnapshot | undefined>;
+  save(
+    jobs: readonly IToolJobState[],
+    expectedRevision: number,
+    abortSignal?: AbortSignal,
+  ): Promise<number>;
+}
+
+export class ToolJobStoreConflictError extends Error {
+  constructor(
+    public readonly expectedRevision: number,
+    public readonly actualRevision: number,
+  ) {
+    super(`Tool job store conflict: expected revision ${expectedRevision}, found ${actualRevision}.`);
+    this.name = 'ToolJobStoreConflictError';
+  }
+}
+
+export const createToolJobSnapshot = (
+  jobs: readonly IToolJobState[],
+  revision: number,
+): IToolJobSnapshot => ({
+  schemaVersion: JOB_SNAPSHOT_SCHEMA_VERSION,
+  revision,
+  updatedAt: Date.now(),
+  jobs: structuredClone([...jobs]),
+});
+
+export class InMemoryToolJobStore implements IToolJobStore {
+  private snapshot: IToolJobSnapshot | undefined;
+
+  public async load(abortSignal?: AbortSignal): Promise<IToolJobSnapshot | undefined> {
+    abortSignal?.throwIfAborted();
+    return this.snapshot ? structuredClone(this.snapshot) : undefined;
+  }
+
+  public async save(
+    jobs: readonly IToolJobState[],
+    expectedRevision: number,
+    abortSignal?: AbortSignal,
+  ): Promise<number> {
+    abortSignal?.throwIfAborted();
+    const actualRevision = this.snapshot?.revision ?? 0;
+    if (actualRevision !== expectedRevision) {
+      throw new ToolJobStoreConflictError(expectedRevision, actualRevision);
+    }
+    const revision = expectedRevision + 1;
+    this.snapshot = createToolJobSnapshot(jobs, revision);
+    return revision;
+  }
+}
+