@modelprofile.com/flexharness 3.5.0 → 3.6.0

package/dist_ts/interfaces.d.ts

@@ -234,6 +234,23 @@ export interface IFlexToolHandle {
 export interface IFlexToolProvider<TScope> {
     provideTools(context: IFlexToolProviderContext<TScope>): Promise<IFlexToolHandle | undefined> | IFlexToolHandle | undefined;
 }
+export interface IFlexResourceToolProviderResolverContext<TScope> {
+    scopeId: string;
+    scope: TScope;
+    sessionId: string;
+    runId: string;
+    readonly parentSessionId?: string;
+    readonly agent?: string;
+    signal: AbortSignal;
+}
+export interface IFlexResourceToolProviderDescriptor<TScope> {
+    resourceId: string;
+    attachmentRevision: number;
+    provider: IFlexToolProvider<TScope>;
+}
+export interface IFlexResourceToolProviderResolver<TScope> {
+    resolveResourceToolProviders(context: IFlexResourceToolProviderResolverContext<TScope>): Promise<readonly IFlexResourceToolProviderDescriptor<TScope>[]> | readonly IFlexResourceToolProviderDescriptor<TScope>[];
+}
 export interface IFlexSessionTombstone {
     sessionId: string;
     deletedAt: string;
@@ -367,6 +384,7 @@ export interface IFlexHarnessOptions<TScope> {
     scopeResolver: IFlexScopeResolver<TScope>;
     modelResolver: IFlexModelResolver<TScope>;
     toolProvider?: IFlexToolProvider<TScope>;
+    resourceToolProviderResolver?: IFlexResourceToolProviderResolver<TScope>;
     executionContextProvider?: IFlexExecutionContextProvider<TScope>;
     stores?: IFlexHarnessStores;
     agentSessionPolicy?: IFlexAgentSessionPolicy<TScope>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelprofile.com/flexharness",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "private": false,
   "description": "Provider-neutral model-session runtime with durable history, permissions, typed events, and pluggable local or remote tool execution.",
   "main": "dist_ts/index.js",

package/readme.hints.md

@@ -8,6 +8,7 @@ Implementation findings for flexharness.
 - Public prompts remain JSON-safe. URL strings are converted to `URL` instances only at the private SmartAgent invocation boundary.
 - Prompt attachment payloads exist only in canonical private Agent events. Public messages, prompt results, projection snapshots, and events expose only `attachmentType`, source kind, optional media/name, and decoded size when determinable.
 - Resolver calls start in promise continuations so synchronous throws are observed. The first failure aborts the shared internal signal without awaiting an ignoring sibling; detached tool-provider settlement is observed and late handles are closed.
+- Resource tool composition resolves descriptors per run before provider acquisition, validates duplicate resources and derived namespaces as one set, preserves legacy tool names, and derives bounded resource names from canonical resource/revision and original-tool hashes. Permission identity uses the complete resource digest while provider metadata remains nested below harness-owned attachment metadata.
 
 ## Persistence boundary
 
@@ -21,6 +22,7 @@ Implementation findings for flexharness.
 - Canonical finalization is the cancellation linearization point. Abort returns false once a run starts committing, while the active-run entry continues to block new prompts until finalization and public promotion settle.
 - Permission callbacks wait for the current save tail and then revalidate their run before reading remembered grants, so neither uncommitted grants nor captured callbacks can authorize later work.
 - Detached tool-provider settlement remains tracked after prompt finalization. Failed late handle closure stays owned by its storage state and is retried by a later retirement or disposal call.
+- A composed tool handle closes resource and application handles in reverse acquisition order. It attempts every close, aggregates failures, marks only successful handles complete, and retains the composite closure so later lifecycle drains retry exactly the failed handles.
 - Scope retirement fences older resolver calls and late state admissions, drains the complete resolved storage namespace, and evicts only the exact cached state promise. It never deletes the durable snapshot. Applications must close admission across every resolver alias before retirement because aliases are unknowable before resolution.
 - Context compaction runs under immutable async invocation context rather than storage-state scope hints. This keeps `scopeId`, `scope`, `storageKey`, and `sessionId` exact for manual, retention, and context-overflow compaction even when aliases share one cached namespace. Autonomous job callbacks use their immutable session-owner context because no later public invocation owns them.
 - Detached tool-provider cleanup and retained session cleanup are owned by the exact loaded storage state. Failed drains retain that ownership and the cached state for retry. Scope retirement cannot await or consume another namespace's cleanup, while full disposal settles all storage drains and orphaned initialization cleanup before aggregating failures.

package/readme.md

@@ -110,6 +110,40 @@ const harness = new FlexHarness<IProjectScope>({
 
 `modelRegistry`, `projectRegistry`, `createProjectTools`, and `closeProjectTools` in this example are application-owned integrations. FlexHarness passes the same run `AbortSignal` to the model resolver and tool provider.
 
+## Resource Tool Providers
+
+`resourceToolProviderResolver` composes zero or more resource-owned providers with the existing application `toolProvider`. The resolver runs fresh for every prompt and returns the current resource attachment descriptors:
+
+```typescript
+resourceToolProviderResolver: {
+  async resolveResourceToolProviders({ scope, sessionId, runId, signal }) {
+    const attachments = await resourceRegistry.listAttached({
+      scope,
+      sessionId,
+      runId,
+      signal,
+    });
+    return attachments.map((attachment) => ({
+      resourceId: attachment.resourceId,
+      attachmentRevision: attachment.attachmentRevision,
+      provider: createResourceToolProvider(attachment),
+    }));
+  },
+},
+```
+
+Each descriptor uses the existing `IFlexToolProvider<TScope>` contract. Its provider receives the normal run context and must return a fresh run-scoped handle. The original `toolProvider` remains optional and its tool names remain unchanged. Resource tool names are deterministic and bounded:
+
+1. `resourceIdentity` is the lowercase hexadecimal SHA-256 of `JSON.stringify([resourceId, attachmentRevision])`.
+2. The namespace is `resource_` plus the first 16 digest characters.
+3. The exposed name is `<namespace>__<stem>__<toolDigest>`. `stem` replaces characters outside `[A-Za-z0-9_-]` with `_`, keeps the first 16 characters, and falls back to `tool`; `toolDigest` is the first 12 lowercase hexadecimal characters of SHA-256 over the original tool name.
+
+The resolver accepts at most 128 descriptors per run. `resourceId` must be non-empty and at most 512 UTF-8 bytes, `attachmentRevision` must be a non-negative safe integer, and each original resource tool name must be non-empty and at most 512 UTF-8 bytes. FlexHarness rejects duplicate `resourceId` values even across revisions, duplicate derived namespaces, and duplicate final exposed tool names before model execution. Descriptor identity and namespace validation completes before any application or resource provider is acquired.
+
+Resource permission requests are scoped with the complete 64-character `resourceIdentity`, not the shortened tool namespace. FlexHarness rewrites `kind` to `resource.<resourceIdentity>.<providerKind>` and an optional `rememberKey` to `resource:<resourceIdentity>:<providerRememberKey>`. Harness-owned metadata contains `resourceId`, `attachmentRevision`, `resourceIdentity`, and `toolNamespace`; provider metadata is nested under `providerMetadata`, so it cannot override attachment identity.
+
+FlexHarness owns every acquired handle. Normal close and partial-failure cleanup run in reverse acquisition order, attempt every handle, aggregate multiple failures, and retain failed cleanup for retirement or disposal retry. Cancellation uses the same path. If model resolution fails while a resource provider is still settling, a late returned handle remains tracked and disposal waits for its closure.
+
 ## Foreground Subagents
 
 `subagents` enables a harness-owned built-in tool named `task`. It is available only when at least one definition exists and the current session depth is below `maxSubagentDepth`. An application `toolProvider` must not return its own `task` tool when subagents are configured. The built-in is foreground-only: the parent tool call does not complete until the child prompt reaches a terminal outcome.
@@ -422,7 +456,7 @@ await migrateLegacyFlexHarnessSnapshot(storageKey, legacySnapshot, stores);
 
 ## Shutdown
 
-Model and tool resolution share the run signal. Synchronous throws are observed as resolver failures; the first failure aborts that signal and finalizes immediately without waiting for an unresponsive sibling. A detached tool provider that resolves later is observed and its handle is closed; disposal waits for that settlement and reports a late close failure.
+Model and tool resolution share the run signal. Synchronous throws are observed as resolver failures; the first failure aborts that signal and finalizes immediately without waiting for an unresponsive sibling. A detached application or resource tool provider that resolves later is observed and every acquired handle is closed; disposal waits for that settlement and reports a late close failure.
 
 Tool-handle close settles before a turn can be successful. After model generation resolves, FlexHarness stages its terminal projection before canonical acceptance; earlier execution failures are finalized as interrupted and then published from that durable outcome. Cleanup failure prevents canonical acceptance. If canonical finalization or public promotion fails, FlexHarness fences the namespace; the next load repairs public state from the durable canonical outcome and any hidden terminal stage.
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/flexharness',
-  version: '3.5.0',
+  version: '3.6.0',
   description: 'Provider-neutral model-session runtime with durable history, permissions, typed events, and pluggable local or remote tool execution.'
 }

package/ts/classes.flexharness.ts

@@ -44,6 +44,7 @@ import type {
   IFlexProjectionSnapshot,
   IFlexResolvedModel,
   IFlexResolvedScope,
+  IFlexResourceToolProviderDescriptor,
   IFlexRunFinishedEvent,
   IFlexScheduledPromptAdmission,
   IFlexSchedulePromptOptions,
@@ -54,6 +55,7 @@ import type {
   IFlexTerminalProjection,
   IFlexToolHandle,
   IFlexToolMessagePart,
+  IFlexToolProviderContext,
   IFlexUncertainToolExecution,
   IFlexUpdateSessionOptions,
   IFlexUsage,
@@ -337,6 +339,10 @@ const defaultMaxSubagentDepth = 1;
 const maximumMaxSubagentDepth = 8;
 const defaultMaxSubagentCallsPerRun = 32;
 const maximumMaxSubagentCallsPerRun = 128;
+const maxResourceToolProviders = 128;
+const maxResourceIdBytes = 512;
+const maxResourceToolNameBytes = 512;
+const resourceToolStemLength = 16;
 const repairCancellationMessage = 'The process stopped before this run completed.';
 const scopeRetirementMessage = 'The scope is being retired.';
 const externalErrorFallback: IFlexErrorInfo = Object.freeze({
@@ -436,6 +442,40 @@ function validateIdentifier(value: string, name: string): void {
   }
 }
 
+function sha256Hex(value: string): string {
+  return plugins.crypto.createHash('sha256').update(value, 'utf8').digest('hex');
+}
+
+function createFlexResourceIdentityDigest(
+  resourceId: string,
+  attachmentRevision: number,
+): string {
+  validateUtf8String(resourceId, 'resourceId', maxResourceIdBytes, true);
+  if (!Number.isSafeInteger(attachmentRevision) || attachmentRevision < 0) {
+    throw new FlexHarnessValidationError('attachmentRevision must be a non-negative safe integer.');
+  }
+  return sha256Hex(JSON.stringify([resourceId, attachmentRevision]));
+}
+
+export function createFlexResourceToolNamespace(
+  resourceId: string,
+  attachmentRevision: number,
+): string {
+  const digest = createFlexResourceIdentityDigest(resourceId, attachmentRevision);
+  return `resource_${digest.slice(0, 16)}`;
+}
+
+export function createFlexResourceToolName(namespace: string, toolName: string): string {
+  if (!/^resource_[a-f0-9]{16}$/u.test(namespace)) {
+    throw new FlexHarnessValidationError('Resource tool namespace is invalid.');
+  }
+  validateUtf8String(toolName, 'resource tool name', maxResourceToolNameBytes, true);
+  const stem = toolName
+    .replace(/[^A-Za-z0-9_-]/gu, '_')
+    .slice(0, resourceToolStemLength) || 'tool';
+  return `${namespace}__${stem}__${sha256Hex(toolName).slice(0, 12)}`;
+}
+
 function validateUtf8String(
   value: unknown,
   name: string,
@@ -859,6 +899,7 @@ export class FlexHarness<TScope = unknown> {
   private readonly scopeResolver: IFlexHarnessOptions<TScope>['scopeResolver'];
   private readonly modelResolver: IFlexHarnessOptions<TScope>['modelResolver'];
   private readonly toolProvider: IFlexHarnessOptions<TScope>['toolProvider'];
+  private readonly resourceToolProviderResolver: IFlexHarnessOptions<TScope>['resourceToolProviderResolver'];
   private readonly executionContextProvider: IFlexHarnessOptions<TScope>['executionContextProvider'];
   private readonly stores: IFlexHarnessStores;
   private readonly agentSessionPolicy: IFlexAgentSessionPolicy<TScope>;
@@ -906,6 +947,7 @@ export class FlexHarness<TScope = unknown> {
     this.scopeResolver = options.scopeResolver;
     this.modelResolver = options.modelResolver;
     this.toolProvider = options.toolProvider;
+    this.resourceToolProviderResolver = options.resourceToolProviderResolver;
     this.executionContextProvider = options.executionContextProvider;
     this.stores = options.stores ?? new InMemoryFlexHarnessStores();
     this.agentSessionPolicy = normalizeAgentSessionPolicy(options.agentSessionPolicy);
@@ -2353,16 +2395,18 @@ export class FlexHarness<TScope = unknown> {
         (value): IResolverOutcome<IFlexResolvedModel> => ({ source: 'model', success: true, value }),
         (error): IResolverOutcome<IFlexResolvedModel> => ({ source: 'model', success: false, error }),
       );
+    const toolProviderContext: Readonly<IFlexToolProviderContext<TScope>> = Object.freeze({
+      scopeId: run.scopeId,
+      scope: run.scope as TScope,
+      sessionId: run.sessionId,
+      runId: run.runId,
+      ...resolverRelationship,
+      signal,
+      requestPermission: (request: IFlexPermissionRequestInput) =>
+        this.requestPermission(run.state, run, request),
+    });
     const toolOutcome = Promise.resolve()
-      .then(() => this.toolProvider?.provideTools(Object.freeze({
-        scopeId: run.scopeId,
-        scope: run.scope as TScope,
-        sessionId: run.sessionId,
-        runId: run.runId,
-        ...resolverRelationship,
-        signal,
-        requestPermission: (request) => this.requestPermission(run.state, run, request),
-      })))
+      .then(() => this.provideRunToolHandle(run, toolProviderContext))
       .then(
         (value): IResolverOutcome<IFlexToolHandle | undefined> => ({ source: 'tools', success: true, value }),
         (error): IResolverOutcome<IFlexToolHandle | undefined> => ({ source: 'tools', success: false, error }),
@@ -3684,6 +3728,161 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
+  private async provideRunToolHandle(
+    run: IActiveRun,
+    context: Readonly<IFlexToolProviderContext<TScope>>,
+  ): Promise<IFlexToolHandle | undefined> {
+    if (!this.resourceToolProviderResolver) return this.toolProvider?.provideTools(context);
+
+    const resolverContext = Object.freeze({
+      scopeId: context.scopeId,
+      scope: context.scope,
+      sessionId: context.sessionId,
+      runId: context.runId,
+      ...(context.parentSessionId === undefined ? {} : { parentSessionId: context.parentSessionId }),
+      ...(context.agent === undefined ? {} : { agent: context.agent }),
+      signal: context.signal,
+    });
+    const resolved = await this.resourceToolProviderResolver.resolveResourceToolProviders(resolverContext);
+    const descriptors = this.normalizeResourceToolProviderDescriptors(resolved);
+    const owned: Array<{ handle: IFlexToolHandle; closed: boolean }> = [];
+    const tools: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+    const closeOwned = async (): Promise<void> => {
+      const errors: unknown[] = [];
+      for (const entry of [...owned].reverse()) {
+        if (entry.closed || !entry.handle.close) continue;
+        try {
+          await entry.handle.close();
+          entry.closed = true;
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+      if (errors.length > 0) throw combineErrors(errors);
+    };
+    try {
+      context.signal.throwIfAborted();
+      const applicationHandle = this.normalizeToolHandle(
+        run,
+        await this.toolProvider?.provideTools(context),
+      );
+      if (applicationHandle) {
+        owned.push({ handle: applicationHandle, closed: false });
+        for (const [toolName, tool] of Object.entries(applicationHandle.tools)) {
+          tools[toolName] = tool;
+        }
+      }
+      for (const descriptor of descriptors) {
+        context.signal.throwIfAborted();
+        const namespace = createFlexResourceToolNamespace(
+          descriptor.resourceId,
+          descriptor.attachmentRevision,
+        );
+        const resourceIdentity = createFlexResourceIdentityDigest(
+          descriptor.resourceId,
+          descriptor.attachmentRevision,
+        );
+        const resourceContext = Object.freeze({
+          ...context,
+          requestPermission: (request: IFlexPermissionRequestInput) => context.requestPermission({
+            ...request,
+            kind: `resource.${resourceIdentity}.${request.kind}`,
+            ...(request.rememberKey === undefined
+              ? {}
+              : { rememberKey: `resource:${resourceIdentity}:${request.rememberKey}` }),
+            metadata: {
+              resourceId: descriptor.resourceId,
+              attachmentRevision: descriptor.attachmentRevision,
+              resourceIdentity,
+              toolNamespace: namespace,
+              ...(request.metadata === undefined ? {} : { providerMetadata: request.metadata }),
+            },
+          }),
+        });
+        const handle = this.normalizeToolHandle(
+          run,
+          await descriptor.provider.provideTools(resourceContext),
+        );
+        if (!handle) continue;
+        owned.push({ handle, closed: false });
+        for (const [toolName, tool] of Object.entries(handle.tools)) {
+          const exposedName = createFlexResourceToolName(namespace, toolName);
+          if (Object.prototype.hasOwnProperty.call(tools, exposedName)) {
+            throw new FlexHarnessValidationError(`Duplicate exposed tool "${exposedName}".`);
+          }
+          tools[exposedName] = tool;
+        }
+      }
+      if (owned.length === 0 && Object.keys(tools).length === 0) return undefined;
+      return {
+        tools: tools as TFlexAgentToolSet,
+        ...(owned.some((entry) => entry.handle.close) ? { close: closeOwned } : {}),
+      };
+    } catch (error) {
+      if (owned.some((entry) => entry.handle.close && !entry.closed)) {
+        try {
+          await this.closePartialToolHandle({ tools: {}, close: closeOwned }, run);
+        } catch (cleanupError) {
+          throw combineErrors([error, cleanupError]);
+        }
+      }
+      throw error;
+    }
+  }
+
+  private normalizeResourceToolProviderDescriptors(
+    descriptors: readonly IFlexResourceToolProviderDescriptor<TScope>[],
+  ): IFlexResourceToolProviderDescriptor<TScope>[] {
+    if (!Array.isArray(descriptors) || descriptors.length > maxResourceToolProviders) {
+      throw new FlexHarnessValidationError(
+        `Resource tool providers must be an array with at most ${maxResourceToolProviders} descriptors.`,
+      );
+    }
+    const resourceIds = new Set<string>();
+    const namespaces = new Set<string>();
+    return descriptors.map((descriptor, index) => {
+      if (
+        !descriptor
+        || typeof descriptor !== 'object'
+        || Array.isArray(descriptor)
+        || ![Object.prototype, null].includes(Object.getPrototypeOf(descriptor))
+      ) {
+        throw new FlexHarnessValidationError(`Resource tool provider descriptor ${index} is invalid.`);
+      }
+      const unsupported = Object.keys(descriptor).find(
+        (key) => !['resourceId', 'attachmentRevision', 'provider'].includes(key),
+      );
+      if (unsupported) {
+        throw new FlexHarnessValidationError(
+          `Resource tool provider descriptor ${index} does not support "${unsupported}".`,
+        );
+      }
+      const resourceId = descriptor.resourceId;
+      const attachmentRevision = descriptor.attachmentRevision;
+      const provider = descriptor.provider;
+      const provideTools = provider?.provideTools;
+      const namespace = createFlexResourceToolNamespace(resourceId, attachmentRevision);
+      if (resourceIds.has(resourceId)) {
+        throw new FlexHarnessValidationError(`Duplicate resourceId "${resourceId}".`);
+      }
+      if (namespaces.has(namespace)) {
+        throw new FlexHarnessValidationError(`Duplicate resource tool namespace "${namespace}".`);
+      }
+      if (!provider || typeof provideTools !== 'function') {
+        throw new FlexHarnessValidationError(`Resource tool provider descriptor ${index} has no tool provider.`);
+      }
+      resourceIds.add(resourceId);
+      namespaces.add(namespace);
+      return {
+        resourceId,
+        attachmentRevision,
+        provider: {
+          provideTools: (context) => provideTools.call(provider, context),
+        },
+      };
+    });
+  }
+
   private async closePartialToolHandle(handle: IFlexToolHandle, run: IActiveRun): Promise<void> {
     try {
       await handle.close?.();

package/ts/interfaces.ts

@@ -300,6 +300,29 @@ export interface IFlexToolProvider<TScope> {
   ): Promise<IFlexToolHandle | undefined> | IFlexToolHandle | undefined;
 }
 
+export interface IFlexResourceToolProviderResolverContext<TScope> {
+  scopeId: string;
+  scope: TScope;
+  sessionId: string;
+  runId: string;
+  readonly parentSessionId?: string;
+  readonly agent?: string;
+  signal: AbortSignal;
+}
+
+export interface IFlexResourceToolProviderDescriptor<TScope> {
+  resourceId: string;
+  attachmentRevision: number;
+  provider: IFlexToolProvider<TScope>;
+}
+
+export interface IFlexResourceToolProviderResolver<TScope> {
+  resolveResourceToolProviders(
+    context: IFlexResourceToolProviderResolverContext<TScope>,
+  ): Promise<readonly IFlexResourceToolProviderDescriptor<TScope>[]>
+    | readonly IFlexResourceToolProviderDescriptor<TScope>[];
+}
+
 export interface IFlexSessionTombstone {
   sessionId: string;
   deletedAt: string;
@@ -494,6 +517,7 @@ export interface IFlexHarnessOptions<TScope> {
   scopeResolver: IFlexScopeResolver<TScope>;
   modelResolver: IFlexModelResolver<TScope>;
   toolProvider?: IFlexToolProvider<TScope>;
+  resourceToolProviderResolver?: IFlexResourceToolProviderResolver<TScope>;
   executionContextProvider?: IFlexExecutionContextProvider<TScope>;
   stores?: IFlexHarnessStores;
   agentSessionPolicy?: IFlexAgentSessionPolicy<TScope>;