@modelprofile.com/flexharness 3.3.0 → 3.5.0

package/ts/interfaces.ts

@@ -90,6 +90,8 @@ export interface IFlexToolMessagePart {
   input: TJsonValue;
   output?: TJsonValue;
   error?: string;
+  childSessionId?: string;
+  model?: IFlexModelIdentity;
 }
 
 export interface IFlexAttachmentMessagePart {
@@ -139,6 +141,11 @@ export interface IFlexSession {
   archivedAt?: string;
   status: TFlexActivityStatus;
   activity: IFlexSessionActivity;
+  parentSessionId?: string;
+  parentRunId?: string;
+  parentToolCallId?: string;
+  agent?: string;
+  depth?: number;
 }
 
 export interface IFlexCreateSessionOptions {
@@ -233,6 +240,8 @@ export interface IFlexModelResolverContext<TScope> {
   sessionId: string;
   runId: string;
   modelHint?: string;
+  readonly parentSessionId?: string;
+  readonly agent?: string;
   signal: AbortSignal;
 }
 
@@ -274,6 +283,8 @@ export interface IFlexToolProviderContext<TScope> {
   scope: TScope;
   sessionId: string;
   runId: string;
+  readonly parentSessionId?: string;
+  readonly agent?: string;
   signal: AbortSignal;
   requestPermission(request: IFlexPermissionRequestInput): Promise<void>;
 }
@@ -292,6 +303,9 @@ export interface IFlexToolProvider<TScope> {
 export interface IFlexSessionTombstone {
   sessionId: string;
   deletedAt: string;
+  rootSessionId?: string;
+  depth?: number;
+  parentSessionId?: string;
 }
 
 export interface IFlexScopeSnapshot {
@@ -441,9 +455,25 @@ export interface IFlexExecutionContextProvider<TScope> {
   ): Promise<IFlexExecutionContextHandle | undefined> | IFlexExecutionContextHandle | undefined;
 }
 
-export interface IFlexAgentSessionPolicy {
+export interface IFlexAgentContextInvocation<TScope = unknown> {
+  readonly scopeId: string;
+  readonly scope: TScope;
+  readonly storageKey: string;
+  readonly sessionId: string;
+}
+
+export interface IFlexAgentContextCompactionOptions<TScope = unknown>
+  extends plugins.IAgentContextCompactionOptions, IFlexAgentContextInvocation<TScope> {}
+
+export type TFlexAgentContextCompactor<TScope = unknown> = (
+  messages: Parameters<plugins.TAgentContextCompactor>[0],
+  events: Parameters<plugins.TAgentContextCompactor>[1],
+  options: IFlexAgentContextCompactionOptions<TScope>,
+) => ReturnType<plugins.TAgentContextCompactor>;
+
+export interface IFlexAgentSessionPolicy<TScope = unknown> {
   contextBuilder?: plugins.TAgentContextBuilder;
-  contextCompactor?: plugins.TAgentContextCompactor;
+  contextCompactor?: TFlexAgentContextCompactor<TScope>;
   eventRetention?: TFlexAgentSessionOptions['eventRetention'];
   changeListenerTimeoutMs?: number;
   maxPendingSessionChanges?: number;
@@ -452,17 +482,28 @@ export interface IFlexAgentSessionPolicy {
   maxContextOverflowRetries?: number;
 }
 
+export interface IFlexSubagentDefinition {
+  name: string;
+  description: string;
+  modelHint?: string;
+  system?: string;
+  maxSteps?: number;
+}
+
 export interface IFlexHarnessOptions<TScope> {
   scopeResolver: IFlexScopeResolver<TScope>;
   modelResolver: IFlexModelResolver<TScope>;
   toolProvider?: IFlexToolProvider<TScope>;
   executionContextProvider?: IFlexExecutionContextProvider<TScope>;
   stores?: IFlexHarnessStores;
-  agentSessionPolicy?: IFlexAgentSessionPolicy;
+  agentSessionPolicy?: IFlexAgentSessionPolicy<TScope>;
   toolOutputLimits?: IFlexJsonLimits;
   callbackLimits?: IFlexCallbackLimits;
   promptQueueLimits?: IFlexPromptQueueLimits;
   externalErrorProjector?: TFlexExternalErrorProjector;
+  subagents?: IFlexSubagentDefinition[];
+  maxSubagentDepth?: number;
+  maxSubagentCallsPerRun?: number;
 }
 
 export interface IFlexUncertainToolExecution {
@@ -539,7 +580,7 @@ export interface IFlexMessageChangedEvent extends IFlexEventBase {
 }
 
 export interface IFlexPartChangedEvent extends IFlexEventBase {
-  readonly type: 'part.started' | 'part.delta' | 'part.completed';
+  readonly type: 'part.started' | 'part.delta' | 'part.updated' | 'part.completed';
   readonly runId: string;
   readonly messageId: string;
   /** Zero-based position in the session's authoritative message sequence. */

package/ts/plugins.ts

@@ -1,9 +1,10 @@
 // node native scope
+import { AsyncLocalStorage } from 'node:async_hooks';
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 
-export { crypto, fs, path };
+export { AsyncLocalStorage, crypto, fs, path };
 
 // @push.rocks scope
 import {
@@ -14,8 +15,10 @@ import {
   createAgentEvent,
   getAgentGenerationTransactions,
   modelMessagesToAgentEvents,
+  tool,
   validateAgentEventArchiveV2,
   validateAgentEventSnapshotV2,
+  z,
 } from '@push.rocks/smartagent';
 
 export {
@@ -26,11 +29,14 @@ export {
   createAgentEvent,
   getAgentGenerationTransactions,
   modelMessagesToAgentEvents,
+  tool,
   validateAgentEventArchiveV2,
   validateAgentEventSnapshotV2,
+  z,
 };
 export type {
   IAgentEventArchiveV2,
+  IAgentContextCompactionOptions,
   IAgentEventSnapshotV2,
   IAgentEventStoreV2,
   IAgentGenerateResult,

package/ts/utils.json.ts

@@ -422,7 +422,7 @@ const activityStatuses = [
   'cancelled',
 ] as const;
 
-function validateSession(value: unknown, path: string): string {
+function validateSession(value: unknown, path: string): IValidatedSessionIdentity {
   const session = requireRecord(value, path);
   requireOnlyKeys(
     session,
@@ -435,6 +435,11 @@ function validateSession(value: unknown, path: string): string {
       'archivedAt',
       'status',
       'activity',
+      'parentSessionId',
+      'parentRunId',
+      'parentToolCallId',
+      'agent',
+      'depth',
     ],
     path,
   );
@@ -456,7 +461,41 @@ function validateSession(value: unknown, path: string): string {
   requireOptionalString(activity.startedAt, `${path}.activity.startedAt`);
   requireOptionalString(activity.completedAt, `${path}.activity.completedAt`);
   requireOptionalString(activity.error, `${path}.activity.error`);
-  return sessionId;
+  const relationship = [
+    session.parentSessionId,
+    session.parentRunId,
+    session.parentToolCallId,
+    session.agent,
+  ];
+  const relationshipCount = relationship.filter((entry) => entry !== undefined).length;
+  if (relationshipCount !== 0 && relationshipCount !== relationship.length) {
+    throw new FlexHarnessStoreFormatError(`${path} has partial subagent relationship fields.`);
+  }
+  for (const [key, entry] of [
+    ['parentSessionId', session.parentSessionId],
+    ['parentRunId', session.parentRunId],
+    ['parentToolCallId', session.parentToolCallId],
+    ['agent', session.agent],
+  ] as const) requireOptionalString(entry, `${path}.${key}`);
+  if (session.depth !== undefined) requireNonNegativeInteger(session.depth, `${path}.depth`);
+  if (relationshipCount === 0 && session.depth !== undefined && session.depth !== 0) {
+    throw new FlexHarnessStoreFormatError(`${path}.depth must be 0 for a root session.`);
+  }
+  if (relationshipCount > 0 && (!Number.isSafeInteger(session.depth) || Number(session.depth) < 1)) {
+    throw new FlexHarnessStoreFormatError(`${path}.depth must be positive for a child session.`);
+  }
+  return {
+    sessionId,
+    ...(relationshipCount === 0
+      ? {}
+      : {
+          parentSessionId: session.parentSessionId as string,
+          parentRunId: session.parentRunId as string,
+          parentToolCallId: session.parentToolCallId as string,
+          agent: session.agent as string,
+        }),
+    ...(session.depth === undefined ? {} : { depth: session.depth as number }),
+  };
 }
 
 function validateModel(value: unknown, path: string): void {
@@ -490,6 +529,15 @@ interface IValidatedMessageIdentity {
   status: 'streaming' | 'completed' | 'failed' | 'cancelled';
 }
 
+interface IValidatedSessionIdentity {
+  sessionId: string;
+  parentSessionId?: string;
+  parentRunId?: string;
+  parentToolCallId?: string;
+  agent?: string;
+  depth?: number;
+}
+
 function validateMessage(value: unknown, path: string): IValidatedMessageIdentity {
   const message = requireRecord(value, path);
   requireOnlyKeys(
@@ -551,7 +599,18 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
     } else if (part.type === 'tool') {
       requireOnlyKeys(
         part,
-        ['partId', 'type', 'toolCallId', 'toolName', 'status', 'input', 'output', 'error'],
+        [
+          'partId',
+          'type',
+          'toolCallId',
+          'toolName',
+          'status',
+          'input',
+          'output',
+          'error',
+          'childSessionId',
+          'model',
+        ],
         partPath,
       );
       requireString(part.toolCallId, `${partPath}.toolCallId`);
@@ -563,6 +622,8 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
         throw new FlexHarnessStoreFormatError(`${partPath}.input is required.`);
       }
       requireOptionalString(part.error, `${partPath}.error`);
+      requireOptionalString(part.childSessionId, `${partPath}.childSessionId`);
+      if (part.model !== undefined) validateModel(part.model, `${partPath}.model`);
     } else if (part.type === 'attachment') {
       requireOnlyKeys(
         part,
@@ -650,23 +711,91 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
     throw new FlexHarnessStoreFormatError('Snapshot sessions must be an array.');
   }
   const sessionIds = new Set<string>();
+  const sessions = new Map<string, IValidatedSessionIdentity>();
   for (let index = 0; index < snapshot.sessions.length; index++) {
-    const sessionId = validateSession(snapshot.sessions[index], `$snapshot.sessions[${index}]`);
-    if (sessionIds.has(sessionId)) {
-      throw new FlexHarnessStoreFormatError(`Snapshot contains duplicate session "${sessionId}".`);
+    const session = validateSession(snapshot.sessions[index], `$snapshot.sessions[${index}]`);
+    if (sessionIds.has(session.sessionId)) {
+      throw new FlexHarnessStoreFormatError(`Snapshot contains duplicate session "${session.sessionId}".`);
+    }
+    sessionIds.add(session.sessionId);
+    sessions.set(session.sessionId, session);
+  }
+  const origins = new Set<string>();
+  for (const session of sessions.values()) {
+    if (!session.parentSessionId) continue;
+    const parent = sessions.get(session.parentSessionId);
+    if (!parent) {
+      throw new FlexHarnessStoreFormatError(
+        `Snapshot child session "${session.sessionId}" has no live parent "${session.parentSessionId}".`,
+      );
+    }
+    const expectedDepth = (parent.depth ?? 0) + 1;
+    if (session.depth !== expectedDepth) {
+      throw new FlexHarnessStoreFormatError(
+        `Snapshot child session "${session.sessionId}" has inconsistent depth.`,
+      );
+    }
+    const origin = JSON.stringify([
+      session.parentSessionId,
+      session.parentRunId,
+      session.parentToolCallId,
+    ]);
+    if (origins.has(origin)) {
+      throw new FlexHarnessStoreFormatError('Snapshot contains duplicate subagent invocation origins.');
+    }
+    origins.add(origin);
+    const ancestors = new Set([session.sessionId]);
+    let current: IValidatedSessionIdentity | undefined = session;
+    while (current.parentSessionId) {
+      if (ancestors.has(current.parentSessionId)) {
+        throw new FlexHarnessStoreFormatError('Snapshot session relationships contain a cycle.');
+      }
+      ancestors.add(current.parentSessionId);
+      current = sessions.get(current.parentSessionId);
+      if (!current) break;
     }
-    sessionIds.add(sessionId);
   }
   if (!Array.isArray(snapshot.tombstones)) {
     throw new FlexHarnessStoreFormatError('Snapshot tombstones must be an array.');
   }
   const tombstoneIds = new Set<string>();
+  const tombstones = new Map<string, {
+    sessionId: string;
+    rootSessionId?: string;
+    depth?: number;
+    parentSessionId?: string;
+  }>();
   for (let index = 0; index < snapshot.tombstones.length; index++) {
     const path = `$snapshot.tombstones[${index}]`;
     const tombstone = requireRecord(snapshot.tombstones[index], path);
-    requireOnlyKeys(tombstone, ['sessionId', 'deletedAt'], path);
+    requireOnlyKeys(
+      tombstone,
+      ['sessionId', 'deletedAt', 'rootSessionId', 'depth', 'parentSessionId'],
+      path,
+    );
     const sessionId = requireString(tombstone.sessionId, `${path}.sessionId`);
     requireString(tombstone.deletedAt, `${path}.deletedAt`);
+    const parentSessionId = tombstone.parentSessionId === undefined
+      ? undefined
+      : requireString(tombstone.parentSessionId, `${path}.parentSessionId`);
+    if (parentSessionId === sessionId) {
+      throw new FlexHarnessStoreFormatError(`${path} cannot be its own parent.`);
+    }
+    const hasRoot = tombstone.rootSessionId !== undefined;
+    const hasDepth = tombstone.depth !== undefined;
+    if (hasRoot !== hasDepth) {
+      throw new FlexHarnessStoreFormatError(`${path} has partial tombstone group fields.`);
+    }
+    if (hasRoot) {
+      requireString(tombstone.rootSessionId, `${path}.rootSessionId`);
+      requireNonNegativeInteger(tombstone.depth, `${path}.depth`);
+      if (tombstone.depth === 0 && tombstone.rootSessionId !== sessionId) {
+        throw new FlexHarnessStoreFormatError(`${path} has an invalid tombstone group root.`);
+      }
+      if (tombstone.depth !== 0 && tombstone.rootSessionId === sessionId) {
+        throw new FlexHarnessStoreFormatError(`${path} has an invalid tombstone group depth.`);
+      }
+    }
     if (tombstoneIds.has(sessionId)) {
       throw new FlexHarnessStoreFormatError(`Snapshot contains duplicate tombstone "${sessionId}".`);
     }
@@ -676,6 +805,71 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
       );
     }
     tombstoneIds.add(sessionId);
+    tombstones.set(sessionId, {
+      sessionId,
+      ...(hasRoot ? { rootSessionId: tombstone.rootSessionId as string } : {}),
+      ...(hasDepth ? { depth: tombstone.depth as number } : {}),
+      ...(parentSessionId === undefined ? {} : { parentSessionId }),
+    });
+  }
+  for (const [index, tombstone] of snapshot.tombstones.entries()) {
+    if (tombstone.rootSessionId === undefined) continue;
+    const root = tombstones.get(tombstone.rootSessionId);
+    if (!root || root.rootSessionId !== root.sessionId || root.depth !== 0) {
+      throw new FlexHarnessStoreFormatError(
+        `$snapshot.tombstones[${index}] references an invalid cleanup group root.`,
+      );
+    }
+  }
+  for (const tombstone of tombstones.values()) {
+    if (tombstone.depth !== undefined && tombstone.depth > 0 && !tombstone.parentSessionId) {
+      throw new FlexHarnessStoreFormatError(
+        `Snapshot grouped tombstone "${tombstone.sessionId}" must retain its parent.`,
+      );
+    }
+    if (!tombstone.parentSessionId) continue;
+    const parentSession = sessions.get(tombstone.parentSessionId);
+    const parentTombstone = tombstones.get(tombstone.parentSessionId);
+    if (!parentSession && !parentTombstone) {
+      throw new FlexHarnessStoreFormatError(
+        `Snapshot tombstone "${tombstone.sessionId}" has no parent "${tombstone.parentSessionId}".`,
+      );
+    }
+    if (tombstone.depth !== undefined && tombstone.depth > 0) {
+      if (
+        !parentTombstone
+        || parentTombstone.rootSessionId !== tombstone.rootSessionId
+        || parentTombstone.depth !== tombstone.depth - 1
+      ) {
+        throw new FlexHarnessStoreFormatError(
+          `Snapshot tombstone "${tombstone.sessionId}" has inconsistent group ancestry.`,
+        );
+      }
+    }
+    const ancestors = new Set([tombstone.sessionId]);
+    let currentId: string | undefined = tombstone.sessionId;
+    while (currentId) {
+      const currentParent: string | undefined = tombstones.get(currentId)?.parentSessionId
+        ?? sessions.get(currentId)?.parentSessionId;
+      if (!currentParent) break;
+      if (ancestors.has(currentParent)) {
+        throw new FlexHarnessStoreFormatError('Snapshot session and tombstone relationships contain a cycle.');
+      }
+      ancestors.add(currentParent);
+      currentId = currentParent;
+    }
+  }
+  const tombstoned = tombstoneIds;
+  for (const session of sessions.values()) {
+    let ancestorId = session.parentSessionId;
+    while (ancestorId) {
+      if (tombstoned.has(ancestorId)) {
+        throw new FlexHarnessStoreFormatError(
+          `Snapshot live session "${session.sessionId}" descends from a tombstoned ancestor.`,
+        );
+      }
+      ancestorId = sessions.get(ancestorId)?.parentSessionId;
+    }
   }
 }