@modelprofile.com/flexharness-agent 6.0.0

package/ts_agent/smartagent.classes.toolregistry.ts

@@ -0,0 +1,26 @@
+import type { ToolSet } from './plugins.js';
+
+export class ToolRegistry {
+  private tools: ToolSet = {};
+
+  /**
+   * Register a tool.
+   * @param name  Tool name (must be unique, snake_case recommended)
+   * @param def   Tool definition created with ai-sdk's tool() helper
+   */
+  public register(name: string, def: ToolSet[string]): this {
+    if (name === 'invalid') {
+      throw new Error('Tool name "invalid" is reserved for SmartAgent tool-call repair.');
+    }
+    if (Object.prototype.hasOwnProperty.call(this.tools, name)) {
+      throw new Error(`Tool "${name}" is already registered.`);
+    }
+    this.tools[name] = def;
+    return this;
+  }
+
+  /** Get the full ToolSet for passing to runAgent */
+  public getTools(): ToolSet {
+    return { ...this.tools };
+  }
+}

package/ts_agent/smartagent.context.ts

@@ -0,0 +1,280 @@
+import type * as plugins from './plugins.js';
+import type {
+  IAgentRuntimeEventPayload,
+  IAssistantMessageEvent,
+  IRuntimeEvent,
+  IToolCallEvent,
+  IToolResultEvent,
+  TAgentAssistantMessage,
+  TAgentEvent,
+  TAgentToolCallPart,
+  TAgentToolResultOutput,
+} from './smartagent.events.js';
+import { filterModelVisibleAgentEvents } from './smartagent.transactions.js';
+
+const eventPriority = (event: TAgentEvent): number => {
+  if (event.type === 'assistant-message') return 0;
+  if (event.type === 'tool-call') return 1;
+  if (event.type === 'tool-result') return 2;
+  return 3;
+};
+
+const orderEvents = (events: readonly TAgentEvent[]): TAgentEvent[] => {
+  const inferenceIds = new Set<string>();
+  for (const event of events) {
+    if (event.type === 'runtime-event' && event.event.type === 'inference-started') {
+      inferenceIds.add(event.id);
+    }
+  }
+  const causedEvents = new Map<string, Array<{ event: TAgentEvent; index: number }>>();
+  for (const [index, event] of events.entries()) {
+    if (!event.causationId || !inferenceIds.has(event.causationId)) continue;
+    const group = causedEvents.get(event.causationId) ?? [];
+    group.push({ event, index });
+    causedEvents.set(event.causationId, group);
+  }
+  const ordered: TAgentEvent[] = [];
+  for (const event of events) {
+    if (event.causationId && inferenceIds.has(event.causationId)) continue;
+    ordered.push(event);
+    if (
+      event.type === 'runtime-event'
+      && event.event.type === 'inference-started'
+    ) {
+      const group = causedEvents.get(event.id) ?? [];
+      for (let priority = 0; priority <= 3; priority++) {
+        ordered.push(...group
+          .filter(({ event: causedEvent }) => eventPriority(causedEvent) === priority)
+          .map(({ event: causedEvent }) => causedEvent));
+      }
+    }
+  }
+  return ordered;
+};
+
+const applyLatestCompaction = (events: readonly TAgentEvent[]): TAgentEvent[] => {
+  const latestCompaction = [...events].reverse().find(
+    (event) => event.type === 'context-compaction',
+  );
+  if (!latestCompaction || latestCompaction.type !== 'context-compaction') {
+    return [...events];
+  }
+  const coveredIds = new Set(latestCompaction.coveredEventIds);
+  return [
+    ...latestCompaction.replacementEvents,
+    ...events.filter((event) => !coveredIds.has(event.id) && event.id !== latestCompaction.id),
+  ];
+};
+
+const assistantToolCallIds = (event: IAssistantMessageEvent): string[] => {
+  if (!Array.isArray(event.content)) return [];
+  return event.content
+    .filter((part): part is TAgentToolCallPart => part.type === 'tool-call')
+    .map((part) => part.toolCallId);
+};
+
+const assistantToolResultIds = (event: IAssistantMessageEvent): string[] => {
+  if (!Array.isArray(event.content)) return [];
+  return event.content
+    .filter((part) => part.type === 'tool-result')
+    .map((part) => part.toolCallId);
+};
+
+const assistantOccurrenceKey = (event: IAssistantMessageEvent, toolCallId: string): string =>
+  `${event.inferenceId ?? event.id}:${toolCallId}`;
+
+const toolOccurrenceKey = (
+  event: IToolCallEvent | IToolResultEvent,
+  assistantEventIds: ReadonlySet<string>,
+): string => {
+  const parentAssistantId = event.parentIds?.find((parentId) => assistantEventIds.has(parentId));
+  return `${parentAssistantId ?? event.inferenceId ?? event.id}:${event.toolCallId}`;
+};
+
+const jsonValue = (value: unknown): unknown => {
+  if (value === undefined) return null;
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return String(value);
+  }
+};
+
+const toModelOutput = (event: IToolResultEvent): TAgentToolResultOutput => {
+  if (event.modelOutput) return event.modelOutput;
+  if (event.error !== undefined) return { type: 'error-text', value: event.error };
+  if (typeof event.output === 'string') return { type: 'text', value: event.output };
+  return { type: 'json', value: jsonValue(event.output) } as TAgentToolResultOutput;
+};
+
+const pushStandaloneToolCall = (
+  messages: plugins.ModelMessage[],
+  event: IToolCallEvent,
+): void => {
+  const part: TAgentToolCallPart = {
+    type: 'tool-call',
+    toolCallId: event.toolCallId,
+    toolName: event.toolName,
+    input: event.input,
+    providerExecuted: event.providerExecuted,
+    providerOptions: event.providerOptions,
+  };
+  const previous = messages[messages.length - 1];
+  if (
+    previous?.role === 'assistant'
+    && Array.isArray(previous.content)
+    && previous.content.every((contentPart) => contentPart.type === 'tool-call')
+  ) {
+    previous.content.push(part);
+    return;
+  }
+  messages.push({ role: 'assistant', content: [part] });
+};
+
+const pushToolResult = (
+  messages: plugins.ModelMessage[],
+  event: IToolResultEvent,
+): void => {
+  messages.push({
+    role: 'tool',
+    content: [{
+      type: 'tool-result',
+      toolCallId: event.toolCallId,
+      toolName: event.toolName,
+      output: toModelOutput(event),
+      providerOptions: event.providerOptions,
+    }],
+    providerOptions: event.messageProviderOptions,
+  });
+};
+
+const formatRuntimeValue = (value: unknown): string => {
+  let formatted: string;
+  try {
+    formatted = JSON.stringify(value, undefined, 2);
+  } catch {
+    formatted = String(value);
+  }
+  const maxLength = 20_000;
+  return formatted.length <= maxLength
+    ? formatted
+    : `${formatted.slice(0, maxLength)}\n[Runtime value truncated]`;
+};
+
+const renderJobRuntimeEvents = (events: readonly IRuntimeEvent[]): string | undefined => {
+  const executionStates = new Map<string, IAgentRuntimeEventPayload>();
+  for (const runtimeEvent of events) {
+    if (runtimeEvent.modelVisible === false || runtimeEvent.event.type === 'inference-started') {
+      continue;
+    }
+    const executionId = runtimeEvent.event.executionId;
+    if (typeof executionId === 'string') {
+      executionStates.set(executionId, {
+        ...executionStates.get(executionId),
+        ...runtimeEvent.event,
+      });
+    }
+  }
+  if (executionStates.size === 0) return undefined;
+
+  const completed: string[] = [];
+  const running: string[] = [];
+  for (const [executionId, state] of executionStates) {
+    if (state.state === 'running') {
+      running.push(`- ${executionId}`);
+    } else {
+      completed.push(`- ${executionId}:\n${formatRuntimeValue(state)}`);
+    }
+  }
+  const sections = ['Runtime update:'];
+  if (completed.length > 0) sections.push(`Completed:\n${completed.join('\n')}`);
+  if (running.length > 0) sections.push(`Still running:\n${running.join('\n')}`);
+  return sections.join('\n\n');
+};
+
+const renderExternalRuntimeEvent = (event: IAgentRuntimeEventPayload): string =>
+  `Runtime update:\n\n${formatRuntimeValue(event)}`;
+
+export function buildModelMessages(events: readonly TAgentEvent[]): plugins.ModelMessage[] {
+  const orderedEvents = orderEvents(applyLatestCompaction(filterModelVisibleAgentEvents(events)));
+  const assistantEventIds = new Set(
+    orderedEvents
+      .filter((event): event is IAssistantMessageEvent => event.type === 'assistant-message')
+      .map((event) => event.id),
+  );
+  const representedToolCalls = new Set<string>();
+  const representedToolResults = new Set<string>();
+  for (const event of orderedEvents) {
+    if (event.type !== 'assistant-message') continue;
+    for (const toolCallId of assistantToolCallIds(event)) {
+      representedToolCalls.add(assistantOccurrenceKey(event, toolCallId));
+    }
+    for (const toolResultId of assistantToolResultIds(event)) {
+      representedToolResults.add(assistantOccurrenceKey(event, toolResultId));
+    }
+  }
+
+  const messages: plugins.ModelMessage[] = [];
+  const jobRuntimeEvents = orderedEvents.filter(
+    (event): event is IRuntimeEvent =>
+      event.type === 'runtime-event'
+      && typeof event.event.executionId === 'string'
+      && event.modelVisible !== false,
+  );
+  let latestJobRuntimeIndex = -1;
+  for (const [index, event] of orderedEvents.entries()) {
+    if (
+      event.type === 'runtime-event'
+      && typeof event.event.executionId === 'string'
+      && event.modelVisible !== false
+    ) {
+      latestJobRuntimeIndex = index;
+    }
+  }
+
+  for (const [index, event] of orderedEvents.entries()) {
+    switch (event.type) {
+      case 'system-message':
+        messages.push({ role: 'system', content: event.content, providerOptions: event.providerOptions });
+        break;
+      case 'user-message':
+        messages.push({ role: 'user', content: event.content, providerOptions: event.providerOptions });
+        break;
+      case 'assistant-message':
+        messages.push({
+          role: 'assistant',
+          content: event.content as TAgentAssistantMessage['content'],
+          providerOptions: event.providerOptions,
+        });
+        break;
+      case 'tool-call':
+        if (!representedToolCalls.has(toolOccurrenceKey(event, assistantEventIds))) {
+          pushStandaloneToolCall(messages, event);
+        }
+        break;
+      case 'tool-result':
+        if (!representedToolResults.has(toolOccurrenceKey(event, assistantEventIds))) {
+          pushToolResult(messages, event);
+        }
+        break;
+      case 'model-message':
+        messages.push(event.message);
+        break;
+      case 'runtime-event':
+        if (event.modelVisible === false || event.event.type === 'inference-started') break;
+        if (typeof event.event.executionId === 'string') {
+          if (index === latestJobRuntimeIndex) {
+            const runtimeUpdate = renderJobRuntimeEvents(jobRuntimeEvents);
+            if (runtimeUpdate) messages.push({ role: 'user', content: runtimeUpdate });
+          }
+        } else {
+          messages.push({ role: 'user', content: renderExternalRuntimeEvent(event.event) });
+        }
+        break;
+      case 'context-compaction':
+        break;
+    }
+  }
+
+  return messages;
+}

package/ts_agent/smartagent.events.ts

@@ -0,0 +1,347 @@
+import * as plugins from './plugins.js';
+
+export type TAgentSystemMessage = Extract<plugins.ModelMessage, { role: 'system' }>;
+export type TAgentUserMessage = Extract<plugins.ModelMessage, { role: 'user' }>;
+export type TAgentAssistantMessage = Extract<plugins.ModelMessage, { role: 'assistant' }>;
+export type TAgentToolMessage = Extract<plugins.ModelMessage, { role: 'tool' }>;
+export type TAgentToolCallPart = Extract<
+  Exclude<TAgentAssistantMessage['content'], string>[number],
+  { type: 'tool-call' }
+>;
+export type TAgentToolResultPart = Extract<
+  TAgentToolMessage['content'][number],
+  { type: 'tool-result' }
+>;
+export type TAgentToolResultOutput = TAgentToolResultPart['output'];
+
+export interface IAgentEventBase {
+  id: string;
+  timestamp: number;
+  /** Monotonic commit order assigned by AgentSession. */
+  sequence?: number;
+  parentIds?: string[];
+  causationId?: string;
+  generationId?: string;
+  inferenceId?: string;
+}
+
+export interface ISystemMessageEvent extends IAgentEventBase {
+  type: 'system-message';
+  content: TAgentSystemMessage['content'];
+  providerOptions?: TAgentSystemMessage['providerOptions'];
+}
+
+export interface IUserMessageEvent extends IAgentEventBase {
+  type: 'user-message';
+  content: TAgentUserMessage['content'];
+  providerOptions?: TAgentUserMessage['providerOptions'];
+}
+
+export interface IAssistantMessageEvent extends IAgentEventBase {
+  type: 'assistant-message';
+  content: TAgentAssistantMessage['content'];
+  providerOptions?: TAgentAssistantMessage['providerOptions'];
+}
+
+export interface IToolCallEvent extends IAgentEventBase {
+  type: 'tool-call';
+  toolCallId: string;
+  toolName: string;
+  input: unknown;
+  providerExecuted?: boolean;
+  providerOptions?: TAgentToolCallPart['providerOptions'];
+}
+
+export interface IToolResultEvent extends IAgentEventBase {
+  type: 'tool-result';
+  toolCallId: string;
+  toolName: string;
+  executionIntentId?: string;
+  output?: unknown;
+  error?: string;
+  modelOutput?: TAgentToolResultOutput;
+  /** True when modelOutput came from an AI SDK response message rather than a provisional callback. */
+  responseMessageCommitted?: boolean;
+  providerOptions?: TAgentToolResultPart['providerOptions'];
+  messageProviderOptions?: TAgentToolMessage['providerOptions'];
+}
+
+export interface IAgentRuntimeEventPayload {
+  type: string;
+  [key: string]: unknown;
+}
+
+export interface IRuntimeEvent extends IAgentEventBase {
+  type: 'runtime-event';
+  event: IAgentRuntimeEventPayload;
+  /** Internal events coordinate projection but are not shown to the model. */
+  modelVisible?: boolean;
+}
+
+export interface IModelMessageEvent extends IAgentEventBase {
+  type: 'model-message';
+  message: plugins.ModelMessage;
+}
+
+export type TAgentGenerationOutcome = 'accepted' | 'rejected' | 'interrupted';
+
+export interface IGenerationBegunEvent extends IAgentEventBase {
+  type: 'generation-begun';
+  generationId: string;
+  claimTokenDigest: string;
+}
+
+export interface IGenerationExecutionStartedEvent extends IAgentEventBase {
+  type: 'generation-execution-started';
+  generationId: string;
+}
+
+export interface IGenerationExecutionCompletedEvent extends IAgentEventBase {
+  type: 'generation-execution-completed';
+  generationId: string;
+}
+
+export interface IGenerationOutcomeEvent extends IAgentEventBase {
+  type: 'generation-outcome';
+  generationId: string;
+  outcome: TAgentGenerationOutcome;
+  reason?: string;
+}
+
+export interface IToolExecutionIntentEvent extends IAgentEventBase {
+  type: 'tool-execution-intent';
+  generationId: string;
+  toolCallId: string;
+  toolName: string;
+  input: unknown;
+}
+
+export type TToolExecutionReconciliation =
+  | 'executed'
+  | 'not-executed'
+  | 'abandoned-unknown';
+
+export interface IToolExecutionReconciliationEvent extends IAgentEventBase {
+  type: 'tool-execution-reconciliation';
+  generationId: string;
+  intentId: string;
+  toolCallId: string;
+  toolName: string;
+  resolution: TToolExecutionReconciliation;
+  output?: unknown;
+  modelOutput?: TAgentToolResultOutput;
+  error?: string;
+}
+
+export type TAgentConversationEvent =
+  | ISystemMessageEvent
+  | IUserMessageEvent
+  | IAssistantMessageEvent
+  | IToolCallEvent
+  | IToolResultEvent
+  | IModelMessageEvent;
+
+export interface IContextCompactionEvent extends IAgentEventBase {
+  type: 'context-compaction';
+  coveredEventIds: string[];
+  replacementEvents: TAgentConversationEvent[];
+  archivedTransactions?: IArchivedAgentGenerationTransaction[];
+}
+
+export interface IArchivedAgentGenerationTransaction {
+  generationId: string;
+  claimTokenDigest: string;
+  outcome: TAgentGenerationOutcome;
+}
+
+export type TAgentControlEvent =
+  | IGenerationBegunEvent
+  | IGenerationExecutionStartedEvent
+  | IGenerationExecutionCompletedEvent
+  | IGenerationOutcomeEvent
+  | IToolExecutionIntentEvent
+  | IToolExecutionReconciliationEvent;
+
+export type TAgentEvent =
+  | TAgentConversationEvent
+  | IRuntimeEvent
+  | IContextCompactionEvent
+  | TAgentControlEvent;
+
+type TEventIdentity = 'id' | 'timestamp' | 'sequence';
+export type TAgentEventInput<TEvent extends TAgentEvent = TAgentEvent> =
+  TEvent extends TAgentEvent
+    ? Omit<TEvent, TEventIdentity> & Partial<Pick<TEvent, TEventIdentity>>
+    : never;
+
+export interface IModelMessagesToEventsOptions {
+  parentIds?: string[];
+  causationId?: string;
+  generationId?: string;
+  inferenceId?: string;
+  identityFactory?: TModelMessageEventIdentityFactory;
+}
+
+export type TModelMessageEmittedEventKind = TAgentConversationEvent['type'];
+
+export interface IModelMessageEventIdentityCoordinates {
+  messageIndex: number;
+  partIndex?: number;
+  eventKind: TModelMessageEmittedEventKind;
+  message: plugins.ModelMessage;
+  part?: unknown;
+  parent?: {
+    messageIndex: number;
+    eventKind: TModelMessageEmittedEventKind;
+    eventId: string;
+  };
+}
+
+export type TModelMessageEventIdentityFactory = (
+  coordinates: IModelMessageEventIdentityCoordinates,
+) => string;
+
+export const createAgentEventId = (prefix = 'event'): string =>
+  `${prefix}_${plugins.crypto.randomUUID()}`;
+
+export function createAgentEvent<TEvent extends TAgentEvent>(
+  event: TAgentEventInput<TEvent>,
+): TEvent {
+  return {
+    ...event,
+    id: event.id ?? createAgentEventId(event.type),
+    timestamp: event.timestamp ?? Date.now(),
+  } as unknown as TEvent;
+}
+
+const modelOutputValue = (output: TAgentToolResultOutput): unknown => {
+  if ('value' in output) return output.value;
+  if (output.type === 'execution-denied') return output.reason;
+  return output;
+};
+
+export function modelMessagesToAgentEvents(
+  messages: readonly plugins.ModelMessage[],
+  options: IModelMessagesToEventsOptions = {},
+): TAgentConversationEvent[] {
+  const events: TAgentConversationEvent[] = [];
+  const causalFields = {
+    parentIds: options.parentIds,
+    causationId: options.causationId,
+    generationId: options.generationId,
+    inferenceId: options.inferenceId,
+  };
+  const identity = (coordinates: IModelMessageEventIdentityCoordinates): { id?: string } => {
+    if (!options.identityFactory) return {};
+    const id = options.identityFactory(coordinates);
+    if (typeof id !== 'string' || !id.trim()) {
+      throw new Error('modelMessagesToAgentEvents identityFactory must return a non-empty string.');
+    }
+    return { id };
+  };
+
+  for (const [messageIndex, message] of messages.entries()) {
+    if (message.role === 'system') {
+      events.push(createAgentEvent<ISystemMessageEvent>({
+        type: 'system-message',
+        content: message.content,
+        providerOptions: message.providerOptions,
+        ...causalFields,
+        ...identity({ messageIndex, eventKind: 'system-message', message }),
+      }));
+      continue;
+    }
+    if (message.role === 'user') {
+      events.push(createAgentEvent<IUserMessageEvent>({
+        type: 'user-message',
+        content: message.content,
+        providerOptions: message.providerOptions,
+        ...causalFields,
+        ...identity({ messageIndex, eventKind: 'user-message', message }),
+      }));
+      continue;
+    }
+    if (message.role === 'assistant') {
+      const assistantEvent = createAgentEvent<IAssistantMessageEvent>({
+        type: 'assistant-message',
+        content: message.content,
+        providerOptions: message.providerOptions,
+        ...causalFields,
+        ...identity({ messageIndex, eventKind: 'assistant-message', message }),
+      });
+      events.push(assistantEvent);
+      if (Array.isArray(message.content)) {
+        for (const [partIndex, part] of message.content.entries()) {
+          if (part.type === 'tool-call') {
+            events.push(createAgentEvent<IToolCallEvent>({
+              type: 'tool-call',
+              toolCallId: part.toolCallId,
+              toolName: part.toolName,
+              input: part.input,
+              providerExecuted: part.providerExecuted,
+              providerOptions: part.providerOptions,
+              parentIds: [assistantEvent.id],
+              causationId: options.causationId,
+              generationId: options.generationId,
+              inferenceId: options.inferenceId,
+              ...identity({
+                messageIndex,
+                partIndex,
+                eventKind: 'tool-call',
+                message,
+                part,
+                parent: {
+                  messageIndex,
+                  eventKind: 'assistant-message',
+                  eventId: assistantEvent.id,
+                },
+              }),
+            }));
+          }
+        }
+      }
+      continue;
+    }
+
+    const toolResultParts = message.content.filter(
+      (part): part is TAgentToolResultPart => part.type === 'tool-result',
+    );
+    if (toolResultParts.length !== message.content.length) {
+      events.push(createAgentEvent<IModelMessageEvent>({
+        type: 'model-message',
+        message,
+        ...causalFields,
+        ...identity({ messageIndex, eventKind: 'model-message', message }),
+      }));
+      continue;
+    }
+    for (const [partIndex, part] of message.content.entries()) {
+      if (part.type !== 'tool-result') continue;
+      events.push(createAgentEvent<IToolResultEvent>({
+        type: 'tool-result',
+        toolCallId: part.toolCallId,
+        toolName: part.toolName,
+        output: modelOutputValue(part.output),
+        error: part.output.type === 'error-text'
+          ? part.output.value
+          : part.output.type === 'error-json'
+            ? JSON.stringify(part.output.value)
+            : undefined,
+        modelOutput: part.output,
+        responseMessageCommitted: true,
+        providerOptions: part.providerOptions,
+        messageProviderOptions: message.providerOptions,
+        ...causalFields,
+        ...identity({
+          messageIndex,
+          partIndex,
+          eventKind: 'tool-result',
+          message,
+          part,
+        }),
+      }));
+    }
+  }
+
+  return events;
+}