@wichayutdew/pi-workflows 0.3.0 → 1.0.0

package/src/integrations/subagents/diagnostic-format.ts

@@ -0,0 +1,40 @@
+import type { ToolFailureDiagnostic } from './diagnostic-types.ts';
+
+/**
+ * Extracts a failed tool name from a terminal error string.
+ */
+export const failedToolName = (error: string | undefined): string | undefined =>
+  error?.match(/\b([a-z][\w-]*) failed(?:\s*\(|:)/i)?.[1];
+
+/**
+ * Formats a correlated tool failure as concise human-readable lines.
+ */
+export const formatToolFailureDiagnostic = (
+  diagnostic: ToolFailureDiagnostic,
+): Array<string> => {
+  const hasSuccessfulOutputCorrelation =
+    diagnostic.correlation === 'successful-output-before-completion';
+  return [
+    `${hasSuccessfulOutputCorrelation ? 'Terminal-reported tool' : 'Failed tool'}: ${diagnostic.tool}`,
+    ...(diagnostic.call
+      ? [
+          `${diagnostic.tool === 'bash' ? 'Command' : 'Arguments'}: ${diagnostic.call}`,
+        ]
+      : []),
+    ...(diagnostic.output
+      ? [
+          `${hasSuccessfulOutputCorrelation ? 'Successful tool output' : 'Tool error'}: ${diagnostic.output}`,
+        ]
+      : []),
+    ...(diagnostic.correlation === 'latest-before-completion'
+      ? [
+          'Correlation: latest failed tool call before successful structured_output; terminal text did not identify the call',
+        ]
+      : []),
+    ...(hasSuccessfulOutputCorrelation
+      ? [
+          'Correlation: terminal error text came from a successful tool result before the final structured_output',
+        ]
+      : []),
+  ];
+};

package/src/integrations/subagents/diagnostic-text.ts

@@ -0,0 +1,114 @@
+const MAX_DIAGNOSTIC_FIELD_CHARS = 1_600;
+const TRUNCATION_MARKER = '… [truncated] …';
+
+/**
+ * Narrows an unknown transcript value to a plain record.
+ */
+export const isDiagnosticRecord = (
+  value: unknown,
+): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * Bounds diagnostic text while preserving evidence from both ends.
+ */
+export const boundedDiagnosticText = (value: string): string => {
+  if (value.length <= MAX_DIAGNOSTIC_FIELD_CHARS) return value;
+  const available = MAX_DIAGNOSTIC_FIELD_CHARS - TRUNCATION_MARKER.length - 2;
+  const startLength = Math.ceil(available / 2);
+  const endLength = Math.floor(available / 2);
+  return `${value.slice(0, startLength)}\n${TRUNCATION_MARKER}\n${value.slice(-endLength)}`;
+};
+
+/**
+ * Joins and bounds every text item in a transcript content array.
+ */
+export const diagnosticTextContent = (value: unknown): string | undefined => {
+  if (!Array.isArray(value)) return undefined;
+  const text = value
+    .flatMap((item) =>
+      isDiagnosticRecord(item) &&
+      item.type === 'text' &&
+      typeof item.text === 'string'
+        ? [item.text]
+        : [],
+    )
+    .join('\n')
+    .trim();
+  return text ? boundedDiagnosticText(text) : undefined;
+};
+
+/**
+ * Returns the first unmodified text item in transcript content.
+ */
+export const firstDiagnosticTextContent = (
+  value: unknown,
+): string | undefined => {
+  if (!Array.isArray(value)) return undefined;
+  const content: ReadonlyArray<unknown> = value;
+  const text = content.find(
+    (item) =>
+      isDiagnosticRecord(item) &&
+      item.type === 'text' &&
+      typeof item.text === 'string',
+  );
+  return isDiagnosticRecord(text) && typeof text.text === 'string'
+    ? text.text
+    : undefined;
+};
+
+/**
+ * Formats a tool call for bounded diagnostic output.
+ */
+export const diagnosticToolCallText = ({
+  tool,
+  argumentsValue,
+}: {
+  readonly tool: string;
+  readonly argumentsValue: unknown;
+}): string | undefined => {
+  if (!isDiagnosticRecord(argumentsValue)) return undefined;
+  if (tool === 'bash') {
+    const command = argumentsValue.command ?? argumentsValue.cmd;
+    if (typeof command === 'string' && command.trim()) {
+      return boundedDiagnosticText(command.trim());
+    }
+  }
+  return boundedDiagnosticText(JSON.stringify(argumentsValue));
+};
+
+/**
+ * Extracts the value from an exclusive structured-output argument shape.
+ */
+export const structuredCompletionValue = (
+  argumentsValue: unknown,
+): Readonly<Record<string, unknown>> | undefined => {
+  if (!isDiagnosticRecord(argumentsValue)) return undefined;
+  if (
+    Object.keys(argumentsValue).length !== 1 ||
+    !Object.hasOwn(argumentsValue, 'value') ||
+    !isDiagnosticRecord(argumentsValue.value)
+  ) {
+    return undefined;
+  }
+  return argumentsValue.value;
+};
+
+const normalizeDiagnosticText = (value: string): string =>
+  value.replace(/\s+/g, ' ').trim().toLowerCase();
+
+/**
+ * Produces normalized, non-trivial fragments for error correlation.
+ */
+export const comparableDiagnosticFragments = (
+  value: string,
+): ReadonlyArray<string> => {
+  const normalizedValue = normalizeDiagnosticText(value);
+  const lines = value
+    .split(/\r?\n/)
+    .map(normalizeDiagnosticText)
+    .filter((line) => line.length >= 8);
+  return [...new Set([normalizedValue, ...lines])].filter(
+    (fragment) => fragment.length >= 8,
+  );
+};

package/src/integrations/subagents/diagnostic-types.ts

@@ -0,0 +1,77 @@
+import type { BashPermission } from '../../config/types.ts';
+
+export type ToolFailureDiagnostic = {
+  readonly tool: string;
+  readonly call?: string;
+  readonly output?: string;
+  readonly replaySafe?: true;
+  readonly completionAfterFailure?: true;
+  readonly completionValue?: Readonly<Record<string, unknown>>;
+  readonly transcriptToolCount?: number;
+  readonly transcriptTurnCount?: number;
+  readonly correlation?:
+    'latest-before-completion' | 'successful-output-before-completion';
+};
+
+export type DelegationReplayAudit = {
+  readonly replaySafe: boolean;
+  readonly toolCount: number;
+};
+
+export type DelegationReplayExpectation = {
+  readonly task: string;
+  readonly bashPermission: BashPermission;
+  readonly approvedBashCommands: ReadonlyArray<string>;
+};
+
+export type SubagentSessionIdentity = {
+  readonly runId: string;
+  readonly childIndex: number;
+};
+
+export type RecordedToolCall = {
+  readonly id: string;
+  readonly order: number;
+  readonly tool: string;
+  readonly call?: string;
+  readonly completionValue?: Readonly<Record<string, unknown>>;
+};
+
+export type RecordedToolFailure = ToolFailureDiagnostic & {
+  readonly callId?: string;
+  readonly order: number;
+};
+
+export type RecordedToolSuccess = {
+  readonly order: number;
+  readonly tool: string;
+  readonly call?: string;
+  readonly output?: string;
+  readonly detectorOutput?: string;
+};
+
+export type RecordedCompletion = {
+  readonly order: number;
+  readonly value: Readonly<Record<string, unknown>>;
+};
+
+export type RecordedMessage = {
+  readonly order: number;
+  readonly value: Readonly<Record<string, unknown>>;
+};
+
+export type ParsedFailureTranscript = {
+  readonly recordedCalls: ReadonlyArray<RecordedToolCall>;
+  readonly diagnostics: ReadonlyArray<RecordedToolFailure>;
+  readonly successfulResults: ReadonlyArray<RecordedToolSuccess>;
+  readonly successfulCompletions: ReadonlyArray<RecordedCompletion>;
+  readonly recordedMessages: ReadonlyArray<RecordedMessage>;
+  readonly resultCallIds: ReadonlySet<string>;
+  readonly hasValidFalsePositiveProof: boolean;
+  readonly lastInteractionOrder: number;
+};
+
+export type SessionTail = {
+  readonly content: string;
+  readonly truncated: boolean;
+};