@sixb/core 0.1.1 → 0.1.3

package/src/actions/run-dispatch.ts

@@ -0,0 +1,276 @@
+import { randomUUID } from "node:crypto"
+import { reportRunFailure } from "../error-reporting/capability"
+import { createSixbError, toSixbFailure } from "../errors/internal"
+import type { DomainEventLog } from "../events"
+import type { Queues } from "../queues"
+import type {
+  ActionRunFailure,
+  ActionRunParams,
+  ActionRunRecord,
+  CreateExecutionInput,
+  Storage,
+} from "../storage"
+import {
+  ACTION_RUN_FAILURE_CODES,
+  ActionRunError,
+  actionRunParamsEqual,
+  actionSubjectsEqual,
+} from "../storage"
+import { parseActionRunFailure } from "../storage/action-runs/failure"
+import type { RequestActionResult } from "./request"
+import { createActionRunId, createActionRunIdempotencyKey } from "./run-id"
+import type { ActionSubject } from "./types"
+
+interface DispatchActionRunInput {
+  readonly errorReporterHost: object
+  readonly projectId: string
+  readonly storage: Storage
+  readonly queue: Queues["actions"]
+  readonly events: DomainEventLog
+  readonly actionId: string
+  readonly subject: ActionSubject
+  readonly params: ActionRunParams
+  readonly runId?: string
+  readonly createExecution: (executionId: string, runId: string) => Promise<CreateExecutionInput>
+}
+
+interface PreparedActionRun {
+  readonly runId: string
+  readonly idempotencyKey: string
+}
+
+type PersistedActionRun =
+  | { readonly publish: false; readonly run: ActionRunRecord }
+  | {
+      readonly publish: true
+      readonly run: ActionRunRecord
+      readonly execution: CreateExecutionInput
+      readonly queuedAt: Date
+      readonly created: boolean
+    }
+
+/** Persist an Action execution and run before publishing its queue job. */
+export async function dispatchActionRun(
+  input: DispatchActionRunInput
+): Promise<RequestActionResult> {
+  const request = prepareActionRun(input)
+  const persisted = await persistActionRun(input, request)
+  if (!persisted.publish) return existingActionRunResult(persisted.run)
+  return publishActionRun(input, persisted)
+}
+
+function prepareActionRun(input: DispatchActionRunInput): PreparedActionRun {
+  const runId = createActionRunId(input.runId)
+  return {
+    runId,
+    idempotencyKey: createActionRunIdempotencyKey(input.projectId, runId),
+  }
+}
+
+async function persistActionRun(
+  input: DispatchActionRunInput,
+  request: PreparedActionRun
+): Promise<PersistedActionRun> {
+  const actionRuns = requireActionRunStorage(input.storage)
+  const existing = await actionRuns.getById({ projectId: input.projectId, id: request.runId })
+  if (existing) return reuseActionRun(input, existing)
+
+  const execution = await input.createExecution(`exec_${randomUUID()}`, request.runId)
+  const queuedAt = new Date()
+  try {
+    return await input.storage.transaction(
+      async (tx): Promise<PersistedActionRun> => {
+        const transactionalRuns = requireActionRunStorage(tx)
+        const raced = await transactionalRuns.getById({
+          projectId: input.projectId,
+          id: request.runId,
+        })
+        if (raced) {
+          assertExistingRunMatchesRequest(raced, input)
+          return { publish: false, run: raced }
+        }
+
+        await tx.executions.create(execution)
+        const run = await transactionalRuns.queue({
+          projectId: input.projectId,
+          id: request.runId,
+          executionId: execution.id,
+          actionId: input.actionId,
+          subject: input.subject,
+          params: input.params,
+          idempotencyKey: request.idempotencyKey,
+          queuedAt,
+        })
+        return { publish: true, run, execution, queuedAt, created: true }
+      },
+      { isolation: "serializable" }
+    )
+  } catch (error) {
+    if (!(error instanceof ActionRunError)) throw error
+    const raced = await actionRuns.getById({ projectId: input.projectId, id: request.runId })
+    if (!raced) throw error
+    assertExistingRunMatchesRequest(raced, input)
+    return { publish: false, run: raced }
+  }
+}
+
+async function reuseActionRun(
+  input: DispatchActionRunInput,
+  existing: ActionRunRecord
+): Promise<PersistedActionRun> {
+  assertExistingRunMatchesRequest(existing, input)
+  if (!isRetryableEnqueueFailure(existing)) return { publish: false, run: existing }
+
+  const execution = await input.storage.executions.getById({
+    projectId: input.projectId,
+    id: existing.executionId,
+  })
+  if (!execution) {
+    throw new ActionRunError(
+      `[Sixb] Execution '${existing.executionId}' for Action run '${existing.id}' was not found.`
+    )
+  }
+
+  const queuedAt = new Date()
+  const run = await requireActionRunStorage(input.storage).queue({
+    projectId: input.projectId,
+    id: existing.id,
+    executionId: existing.executionId,
+    actionId: existing.actionId,
+    subject: existing.subject,
+    params: existing.params,
+    idempotencyKey: existing.idempotencyKey,
+    queuedAt,
+  })
+  return { publish: true, run, execution, queuedAt, created: false }
+}
+
+async function publishActionRun(
+  input: DispatchActionRunInput,
+  persisted: Extract<PersistedActionRun, { readonly publish: true }>
+): Promise<RequestActionResult> {
+  let job: Awaited<ReturnType<Queues["actions"]["enqueue"]>>[number] | undefined
+  try {
+    const jobs = await input.queue.enqueue({
+      projectId: input.projectId,
+      jobs: [
+        {
+          id: persisted.run.id,
+          type: "action.run.requested",
+          payload: {
+            runId: persisted.run.id,
+          },
+        },
+      ],
+    })
+    job = jobs[0]
+  } catch (error) {
+    await failActionRunPublication(input, persisted.run, error)
+    throw error
+  }
+
+  await input.events.emit(
+    {
+      events: [
+        {
+          type: "action.requested",
+          payload: {
+            actionId: persisted.run.actionId,
+            subject: persisted.run.subject,
+            params: persisted.run.params,
+            runId: persisted.run.id,
+          },
+        },
+      ],
+      correlationId: persisted.execution.correlationId,
+    },
+    { source: "Sixb" }
+  )
+
+  return {
+    runId: persisted.run.id,
+    queuedAt: persisted.queuedAt.toISOString(),
+    ...(job?.id ? { jobId: job.id } : {}),
+    created: persisted.created,
+  }
+}
+
+async function failActionRunPublication(
+  input: DispatchActionRunInput,
+  run: ActionRunRecord,
+  error: unknown
+): Promise<void> {
+  const failedAt = new Date()
+  const failure = toActionRunFailure(error, run, failedAt)
+  await requireActionRunStorage(input.storage).finish({
+    projectId: input.projectId,
+    id: run.id,
+    status: "failed",
+    finishedAt: failedAt,
+    error: failure,
+  })
+  reportRunFailure(input.errorReporterHost, error, {
+    projectId: input.projectId,
+    runKind: "action",
+    run: { runId: run.id, actionId: run.actionId },
+    failure,
+  })
+}
+
+function requireActionRunStorage(storage: Storage): NonNullable<Storage["actionRuns"]> {
+  if (!storage.actionRuns) {
+    throw new ActionRunError("[Sixb] Action run storage is not configured.")
+  }
+  return storage.actionRuns
+}
+
+function assertExistingRunMatchesRequest(
+  existing: ActionRunRecord,
+  request: Pick<DispatchActionRunInput, "actionId" | "subject" | "params">
+): void {
+  if (
+    existing.actionId !== request.actionId ||
+    !actionSubjectsEqual(existing.subject, request.subject) ||
+    !actionRunParamsEqual(existing.params, request.params)
+  ) {
+    throw new ActionRunError(
+      `[Sixb] Action run '${existing.id}' already exists with a different request payload.`
+    )
+  }
+}
+
+function isRetryableEnqueueFailure(record: ActionRunRecord): boolean {
+  return (
+    record.status === "failed" && record.phase === "enqueue" && record.error?.retryable === true
+  )
+}
+
+function existingActionRunResult(existing: ActionRunRecord): RequestActionResult {
+  return {
+    runId: existing.id,
+    queuedAt: existing.queuedAt.toISOString(),
+    created: false,
+  }
+}
+
+function toActionRunFailure(
+  error: unknown,
+  run: ActionRunRecord,
+  at: Date
+): ActionRunFailure<"enqueue"> {
+  const enqueueError = createSixbError(
+    "queue.enqueue_failed",
+    `[Sixb] Could not enqueue Action run '${run.id}'.`,
+    {
+      cause: error,
+      details: { actionId: run.actionId, runId: run.id, phase: "enqueue" },
+    }
+  )
+  return parseActionRunFailure(
+    toSixbFailure(enqueueError, {
+      allowedCodes: ACTION_RUN_FAILURE_CODES,
+      at,
+    }),
+    "enqueue"
+  )
+}

package/src/actions/types/context.ts

@@ -1,5 +1,5 @@
 import type { BlobStorage } from "../../blob-storage"
-import type { ConnectorAdapter, ConnectorClient, ConnectorDefinition } from "../../connectors"
+import type { ConnectorRuntime } from "../../connectors"
 import type { RecordEditsContext } from "../../edits"
 import type { Logger } from "../../logging"
 import type {
@@ -129,12 +129,10 @@ export interface ActionRuntimeFacade<
   TValueTypes extends readonly ValueType[] = readonly ValueType[],
 > {
   readonly blobs: ActionBlobContext
+  readonly connector: ConnectorRuntime
   objects<const TObjectType extends ObjectTypeWithPropertyTokens>(
     objectType: TObjectType
   ): ActionTelemetryObjectSet<TObjectType, TValueTypes>
-  connector<TAdapter extends ConnectorAdapter>(
-    definition: ConnectorDefinition<string, TAdapter>
-  ): Promise<ConnectorClient<TAdapter>>
 }
 
 /**

package/src/actions/validation.ts

@@ -20,7 +20,7 @@ interface ActionValidationRuntime {
     resolveObjectType(objectTypeId: string): ObjectTypeWithPropertyTokens
   }
   readonly actionRegistry: {
-    getActionsForType(objectType: ObjectTypeWithPropertyTokens): readonly ObjectActionDefinition[]
+    listForType(objectType: ObjectTypeWithPropertyTokens): readonly ObjectActionDefinition[]
   }
 }
 
@@ -164,7 +164,7 @@ function actionAppliesToObjectType(
   objectType: ObjectTypeWithPropertyTokens
 ): boolean {
   return runtime.actionRegistry
-    .getActionsForType(objectType)
+    .listForType(objectType)
     .some((candidate) => candidate.id === action.id)
 }
 

package/src/agents/adapters.ts

@@ -8,7 +8,9 @@ import {
 } from "./context"
 import { serializeAgentContextForModel } from "./context-model"
 import { AgentMessageAdapterError } from "./errors"
-import type { AgentMessage, AgentMessagePart, AgentMessageRole } from "./message"
+import type { AgentMessage, AgentMessagePart, AgentMessageRole, AgentToolCallPart } from "./message"
+import { isAgentToolResult } from "./tool-result"
+import type { AgentToolFileContent } from "./types"
 
 // ── Inbound (write) — deliberately WIDE ────────────────────────────────────────────────────────
 //
@@ -159,6 +161,14 @@ export interface AgentFileDataProjection {
   readonly filename?: string
 }
 
+export interface AgentToolResultFileResolverInput<TMessage extends AgentMessage = AgentMessage> {
+  readonly message: TMessage
+  readonly part: AgentToolCallPart
+  readonly partIndex: number
+  readonly contentPart: AgentToolFileContent
+  readonly contentIndex: number
+}
+
 export interface ToModelMessagesOptions<TMessage extends AgentMessage = AgentMessage> {
   /**
    * Convert a stored file reference into model-readable data. When omitted, file parts are skipped
@@ -173,6 +183,10 @@ export interface ToModelMessagesOptions<TMessage extends AgentMessage = AgentMes
    * models that cannot consume inline files.
    */
   readonly fileText?: (input: AgentFileDataResolverInput<TMessage>) => string | undefined
+  /** Add current metadata, sandbox paths, and projection notes for a tool-result file. */
+  readonly toolResultFileText?: (
+    input: AgentToolResultFileResolverInput<TMessage>
+  ) => string | undefined
 }
 
 // ── Helpers ─────────────────────────────────────────────────────────────────────────────────────
@@ -210,7 +224,11 @@ function optionalJson(value: unknown, label: string): JsonValue | undefined {
  * and every other non-JSON shape are left for `requireJson` to accept or reject. This helper only
  * turns `{ key: undefined }` into `{}` for metadata compatibility with SDK output.
  */
-function omitUndefinedObjectProperties(value: unknown, seen = new Set<object>()): unknown {
+export function omitUndefinedObjectProperties(value: unknown): unknown {
+  return omitUndefinedObjectPropertiesInternal(value, new Set())
+}
+
+function omitUndefinedObjectPropertiesInternal(value: unknown, seen: Set<object>): unknown {
   if (typeof value !== "object" || value === null) return value
 
   // Avoid recursing forever on a malformed/cyclic metadata object. Leaving the cycle in place lets
@@ -220,7 +238,7 @@ function omitUndefinedObjectProperties(value: unknown, seen = new Set<object>())
   seen.add(value)
   try {
     if (Array.isArray(value)) {
-      return value.map((entry) => omitUndefinedObjectProperties(entry, seen))
+      return value.map((entry) => omitUndefinedObjectPropertiesInternal(entry, seen))
     }
 
     if (!isPlainRecord(value)) return value
@@ -228,7 +246,7 @@ function omitUndefinedObjectProperties(value: unknown, seen = new Set<object>())
     return Object.fromEntries(
       Object.entries(value)
         .filter(([, entry]) => entry !== undefined)
-        .map(([key, entry]) => [key, omitUndefinedObjectProperties(entry, seen)])
+        .map(([key, entry]) => [key, omitUndefinedObjectPropertiesInternal(entry, seen)])
     )
   } finally {
     seen.delete(value)
@@ -333,7 +351,7 @@ function fromUiContextPart(part: AgentInboundUiMessagePart): AgentMessagePart {
   }
 }
 
-function fromAiSdkToolPart(part: AgentInboundUiMessagePart): AgentToolCallPartResult {
+function fromAiSdkToolPart(part: AgentInboundUiMessagePart): AgentToolCallPart {
   const dynamic = part.type === "dynamic-tool"
   const toolName = toolNameFromInbound(part)
   assertAdapter(
@@ -369,8 +387,6 @@ function fromAiSdkToolPart(part: AgentInboundUiMessagePart): AgentToolCallPartRe
   return { ...base, state: "output-error", errorText: part.errorText }
 }
 
-type AgentToolCallPartResult = Extract<AgentMessagePart, { type: "tool-call" }>
-
 // ── toUiMessage (read) ────────────────────────────────────────────────────────────────────────
 
 /** Reconstruct an SDK-shaped UI message from a stored message. Exact inverse of {@link fromAiSdk}. */
@@ -406,7 +422,7 @@ function toUiPart(part: AgentMessagePart): AgentUiMessagePart {
   }
 }
 
-function toUiToolPart(part: AgentToolCallPartResult): AgentUiToolPart {
+function toUiToolPart(part: AgentToolCallPart): AgentUiToolPart {
   const body = {
     toolCallId: part.toolCallId,
     ...(part.providerExecuted === undefined ? {} : { providerExecuted: part.providerExecuted }),
@@ -566,17 +582,17 @@ function appendAssistantModelMessages<TMessage extends AgentMessage>(
       } else if (part.type === "tool-call") {
         content.push(toolCallModelPart(part))
         if (part.providerExecuted === true) {
-          content.push(toolResultModelPart(part, "json"))
+          content.push(toolResultModelPart(message, part, partIndex, "json", options))
         }
       }
     }
     result.push({ role: "assistant", content })
 
-    const toolResults = current
-      .map(({ part }) => part)
-      .filter(isToolCallPart)
-      .filter((part) => part.providerExecuted !== true)
-      .map((part) => toolResultModelPart(part, "text"))
+    const toolResults = current.flatMap(({ part, partIndex }) =>
+      part.type === "tool-call" && part.providerExecuted !== true
+        ? [toolResultModelPart(message, part, partIndex, "text", options)]
+        : []
+    )
     if (toolResults.length > 0) {
       result.push({ role: "tool", content: toolResults })
     }
@@ -592,7 +608,7 @@ function appendAssistantModelMessages<TMessage extends AgentMessage>(
   flush()
 }
 
-function toolCallModelPart(part: AgentToolCallPartResult): AgentModelToolCallPart {
+function toolCallModelPart(part: AgentToolCallPart): AgentModelToolCallPart {
   return {
     type: "tool-call",
     toolCallId: part.toolCallId,
@@ -603,37 +619,66 @@ function toolCallModelPart(part: AgentToolCallPartResult): AgentModelToolCallPar
   }
 }
 
-function toolResultModelPart(
-  part: AgentToolCallPartResult,
-  errorMode: "text" | "json"
+function toolResultModelPart<TMessage extends AgentMessage>(
+  message: TMessage,
+  part: AgentToolCallPart,
+  partIndex: number,
+  errorMode: "text" | "json",
+  options: ToModelMessagesOptions<TMessage>
 ): AgentModelToolResultPart {
   return {
     type: "tool-result",
     toolCallId: part.toolCallId,
     toolName: part.toolName,
-    output: toolResultOutput(part, errorMode),
+    output: toolResultOutput(message, part, partIndex, errorMode, options),
     ...(part.providerMetadata === undefined ? {} : { providerOptions: part.providerMetadata }),
   }
 }
 
-function toolResultOutput(
-  part: AgentToolCallPartResult,
-  errorMode: "text" | "json"
+function toolResultOutput<TMessage extends AgentMessage>(
+  message: TMessage,
+  part: AgentToolCallPart,
+  partIndex: number,
+  errorMode: "text" | "json",
+  options: ToModelMessagesOptions<TMessage>
 ): AgentModelToolOutput {
   if (part.state === "output-error") {
     return errorMode === "json"
       ? { type: "error-json", value: part.errorText }
       : { type: "error-text", value: part.errorText }
   }
+  if (isAgentToolResult(part.output)) {
+    const value: string[] = []
+    part.output.content.forEach((contentPart, contentIndex) => {
+      if (contentPart.type === "text") {
+        value.push(contentPart.text)
+        return
+      }
+
+      const resolverInput = { message, part, partIndex, contentPart, contentIndex }
+      const fileContext = options.toolResultFileText?.(resolverInput)
+      if (fileContext) {
+        value.push(fileContext)
+      } else {
+        value.push(toolResultFileFallbackText(contentPart))
+      }
+    })
+    return { type: "text", value: value.join("\n") }
+  }
   return typeof part.output === "string"
     ? { type: "text", value: part.output }
     : { type: "json", value: part.output }
 }
 
-function isTextPart(part: AgentMessagePart): part is Extract<AgentMessagePart, { type: "text" }> {
-  return part.type === "text"
+function toolResultFileFallbackText(part: AgentToolFileContent): string {
+  const attributes = [
+    part.fileRef.fileName ? `name=${JSON.stringify(part.fileRef.fileName)}` : undefined,
+    part.fileRef.mediaType ? `mediaType=${JSON.stringify(part.fileRef.mediaType)}` : undefined,
+    `sizeBytes=${part.fileRef.sizeBytes}`,
+  ].filter((value): value is string => value !== undefined)
+  return `[Tool-created file: ${attributes.join(" ")}. Contents are not available inline.]`
 }
 
-function isToolCallPart(part: AgentMessagePart): part is AgentToolCallPartResult {
-  return part.type === "tool-call"
+function isTextPart(part: AgentMessagePart): part is Extract<AgentMessagePart, { type: "text" }> {
+  return part.type === "text"
 }