@ai-sdk/harness 0.0.0 → 1.0.0-beta.14

package/src/agent/internal/lifecycle-state-validation.ts

@@ -0,0 +1,95 @@
+import { safeValidateTypes } from '@ai-sdk/provider-utils';
+import { HarnessError } from '../../errors/harness-error';
+import type { HarnessV1, HarnessV1LifecycleState } from '../../v1';
+
+/**
+ * Validate a lifecycle state against the harness's contract:
+ *  - `type` must match the lifecycle method that will consume it.
+ *  - `specificationVersion` must be `'harness-v1'`.
+ *  - `harnessId` must match the harness producing/consuming the payload.
+ *  - When the harness declares a `lifecycleStateSchema`, `data` is parsed
+ *    against it.
+ *
+ * Returns the payload with `data` replaced by the parsed value when a
+ * schema is present, so callers downstream see a canonical shape.
+ */
+export async function validateLifecycleStateData<
+  STATE extends HarnessV1LifecycleState,
+>(input: {
+  harness: HarnessV1;
+  state: STATE;
+  expectedType: STATE['type'];
+}): Promise<STATE> {
+  const { harness, state } = input;
+  if (state.type !== input.expectedType) {
+    throw new HarnessError({
+      message: `Lifecycle state has unexpected type '${state.type}'; expected '${input.expectedType}'.`,
+    });
+  }
+  if (state.specificationVersion !== 'harness-v1') {
+    throw new HarnessError({
+      message: `Lifecycle state has unexpected specificationVersion '${state.specificationVersion}'; expected 'harness-v1'.`,
+    });
+  }
+  if (state.harnessId !== harness.harnessId) {
+    throw new HarnessError({
+      message: `Lifecycle state was produced by harness '${state.harnessId}' but this agent uses '${harness.harnessId}'.`,
+    });
+  }
+  if (
+    state.type === 'resume-session' &&
+    'pendingToolApprovals' in state &&
+    state.pendingToolApprovals !== undefined
+  ) {
+    throw new HarnessError({
+      message:
+        'Resume session state cannot contain pending tool approvals; unfinished turns must be stored as `continueFrom`.',
+    });
+  }
+
+  const data =
+    harness.lifecycleStateSchema == null
+      ? state.data
+      : await (async () => {
+          const result = await safeValidateTypes({
+            value: state.data,
+            schema: harness.lifecycleStateSchema!,
+          });
+          if (!result.success) {
+            throw new HarnessError({
+              message: `Lifecycle state failed schema validation for harness '${harness.harnessId}': ${result.error.message}`,
+              cause: result.error,
+            });
+          }
+          return result.value as STATE['data'];
+        })();
+
+  if (state.type === 'resume-session') {
+    const continueFrom =
+      state.continueFrom == null
+        ? undefined
+        : await validateLifecycleStateData({
+            harness,
+            state: state.continueFrom,
+            expectedType: 'continue-turn',
+          });
+
+    return {
+      type: state.type,
+      harnessId: state.harnessId,
+      specificationVersion: state.specificationVersion,
+      data,
+      ...(continueFrom !== undefined ? { continueFrom } : {}),
+    } as STATE;
+  }
+
+  return {
+    type: state.type,
+    harnessId: state.harnessId,
+    specificationVersion: state.specificationVersion,
+    data,
+    ...(state.pendingToolApprovals !== undefined
+      ? { pendingToolApprovals: state.pendingToolApprovals }
+      : {}),
+  } as STATE;
+}

package/src/agent/internal/permission-mode.ts

@@ -0,0 +1,50 @@
+import type { ToolApprovalStatus } from 'ai';
+import type { HarnessV1PermissionMode } from '../../v1';
+import type { HarnessAgentToolApprovalConfiguration } from '../harness-agent-settings';
+
+export const DEFAULT_PERMISSION_MODE: HarnessV1PermissionMode =
+  'allow-all' as const;
+
+export function resolvePermissionMode(input: {
+  permissionMode: HarnessV1PermissionMode | undefined;
+}): HarnessV1PermissionMode {
+  return input.permissionMode ?? DEFAULT_PERMISSION_MODE;
+}
+
+export function permissionModeNeedsBuiltinSupport(input: {
+  permissionMode: HarnessV1PermissionMode;
+}): boolean {
+  return input.permissionMode !== 'allow-all';
+}
+
+export type CustomToolApprovalDecision =
+  | { readonly type: 'allow'; readonly reason?: string }
+  | { readonly type: 'deny'; readonly reason?: string }
+  | { readonly type: 'request' };
+
+export function resolveCustomToolApproval(input: {
+  toolName: string;
+  toolApproval: HarnessAgentToolApprovalConfiguration | undefined;
+}): CustomToolApprovalDecision {
+  const status = normalizeToolApprovalStatus({
+    status: input.toolApproval?.[input.toolName],
+  });
+
+  switch (status.type) {
+    case 'not-applicable':
+    case 'approved':
+      return { type: 'allow', reason: status.reason };
+    case 'denied':
+      return { type: 'deny', reason: status.reason };
+    case 'user-approval':
+      return { type: 'request' };
+  }
+}
+
+function normalizeToolApprovalStatus(input: {
+  status: ToolApprovalStatus | undefined;
+}): Exclude<ToolApprovalStatus, string | undefined> {
+  if (input.status === undefined) return { type: 'not-applicable' };
+  if (typeof input.status === 'string') return { type: input.status };
+  return input.status;
+}

package/src/agent/internal/resolve-observability.ts

@@ -0,0 +1,128 @@
+import { asArray } from '@ai-sdk/provider-utils';
+import type { Telemetry } from 'ai';
+import type { HarnessV1Diagnostic, HarnessV1Observability } from '../../v1';
+import type {
+  HarnessDebugConfig,
+  HarnessDebugLevel,
+  HarnessDiagnostic,
+  HarnessDiagnosticConsumer,
+} from '../observability/types';
+import type { HarnessAgentSettings } from '../harness-agent-settings';
+
+const ENV_TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+
+function parseList(value: string | undefined): string[] | undefined {
+  if (!value) return undefined;
+  const items = value
+    .split(',')
+    .map(item => item.trim())
+    .filter(Boolean);
+  return items.length > 0 ? items : undefined;
+}
+
+/**
+ * Resolve the effective debug config from explicit settings with env-var
+ * fallbacks. `HARNESS_DEBUG*` only fill fields the consumer left unset — code is
+ * always authoritative.
+ */
+export function resolveDebugConfig(
+  debug: HarnessDebugConfig | undefined,
+  env: Record<string, string | undefined> = process.env,
+): {
+  enabled: boolean;
+  level: HarnessDebugLevel;
+  subsystems: string[] | undefined;
+} {
+  const enabled =
+    debug?.enabled ?? ENV_TRUTHY.has((env.HARNESS_DEBUG ?? '').toLowerCase());
+  const level =
+    debug?.level ??
+    (env.HARNESS_DEBUG_LEVEL as HarnessDebugLevel | undefined) ??
+    'debug';
+  const subsystems = debug?.subsystems
+    ? [...debug.subsystems]
+    : parseList(env.HARNESS_DEBUG_SUBSYSTEMS);
+  return { enabled, level, subsystems };
+}
+
+/**
+ * Map an adapter-emitted `HarnessV1Diagnostic` to the host-facing
+ * `HarnessDiagnostic` (the external/telemetry surface). Identity-shaped today,
+ * but an explicit boundary so the emission and consumption types can diverge.
+ */
+function toHarnessDiagnostic(d: HarnessV1Diagnostic): HarnessDiagnostic {
+  return {
+    level: d.level,
+    message: d.message,
+    subsystem: d.subsystem,
+    kind: d.kind,
+    source: d.source,
+    stream: d.stream,
+    attrs: d.attrs,
+    error: d.error,
+    sessionId: d.sessionId,
+    timestamp: d.timestamp,
+  };
+}
+
+function formatForStderr(d: HarnessDiagnostic): string {
+  const parts = [`[harness:${d.level}]`, d.subsystem, d.message].filter(
+    Boolean,
+  );
+  let line = parts.join(' ');
+  if (d.error) {
+    line += ` (${d.error.name ?? 'Error'}: ${d.error.message})`;
+  }
+  return `${line}\n`;
+}
+
+/**
+ * Build the per-session observability handle the framework hands to `doStart`.
+ * Returns `undefined` when diagnostics are disabled. When enabled, the `report`
+ * sink maps each adapter-emitted `HarnessV1Diagnostic` to the host
+ * `HarnessDiagnostic` and fans it out, non-lossy, to: the `HARNESS_DEBUG` stderr
+ * default, the consumer's `onLog`, and any telemetry integration that
+ * implements `ingestDiagnostic`. Adapters normalize their own source (bridge
+ * wire frames, host logs) into `HarnessV1Diagnostic` before calling `report`.
+ */
+export function buildObservability(options: {
+  settings: Pick<
+    HarnessAgentSettings<any, any>,
+    'debug' | 'onLog' | 'telemetry'
+  >;
+}): HarnessV1Observability | undefined {
+  const resolved = resolveDebugConfig(options.settings.debug);
+  if (!resolved.enabled) return undefined;
+
+  const onLog = options.settings.onLog;
+  const integrations = options.settings.telemetry?.integrations
+    ? asArray(options.settings.telemetry.integrations)
+    : [];
+  const diagnosticConsumers = integrations.filter(
+    (integration): integration is Telemetry & HarnessDiagnosticConsumer =>
+      typeof (integration as HarnessDiagnosticConsumer).ingestDiagnostic ===
+      'function',
+  );
+
+  const report = (emitted: HarnessV1Diagnostic): void => {
+    const diagnostic = toHarnessDiagnostic(emitted);
+    try {
+      process.stderr.write(formatForStderr(diagnostic));
+    } catch {
+      // Never let the stderr default break the turn.
+    }
+    onLog?.(diagnostic);
+    for (const consumer of diagnosticConsumers) {
+      consumer.ingestDiagnostic?.(diagnostic);
+    }
+  };
+
+  return {
+    debug: {
+      enabled: true,
+      level: resolved.level,
+      ...(resolved.subsystems ? { subsystems: resolved.subsystems } : {}),
+    },
+    report,
+  };
+}