Low-level utilities

These utilities expose runtime composition state for framework and wrapper authors. They aren’t business correlation keys. Prefer ordinary signal dependencies and correlationId when they express the relationship.

`getNextHookLocation`

Returns the next durable hook location without reserving it:

function getNextHookLocation(): HookLocation | undefined

interface HookLocation {
  readonly scopePath: readonly number[]
  readonly slot: number
}

Call it immediately before the durable declaration a low-level wrapper associates with that location:

automations/report-hook-location.automation.ts

import {
  automation,
  getNextHookLocation,
  onHttpRequest,
  respondToHttpRequest,
} from "automate.ax"

export default automation("Report response hook", () => {
  const request = onHttpRequest()
  const location = getNextHookLocation()

  respondToHttpRequest({
    body: location
      ? { scopePath: [...location.scopePath], slot: location.slot }
      : null,
    requestId: request.requestId,
  })
})

The function returns undefined outside an active automation traversal. Inspection doesn’t consume the slot. Hook locations identify replay structure, not business entities or occurrences.

`getAutomationExecutionIdentity`

Returns the active automation and context IDs during execution:

function getAutomationExecutionIdentity():
  | AutomationExecutionIdentity
  | undefined

interface AutomationExecutionIdentity {
  readonly automationId: string
  readonly contextId: string
}

Planning has no execution context. Call the function from runtime code such as a custom action handler:

automations/report-execution-identity.automation.ts

import {
  automation,
  defineAction,
  getAutomationExecutionIdentity,
  onHttpRequest,
  respondToHttpRequest,
} from "automate.ax"
import { z } from "zod"

const readIdentity = defineAction("Read execution identity")
  .input(z.object({}))
  .output(z.object({ automationId: z.string(), contextId: z.string() }))
  .handler(() => {
    const identity = getAutomationExecutionIdentity()
    if (!identity) throw new Error("Execution identity is unavailable.")
    return identity
  })

export default automation("Report execution identity", () => {
  const request = onHttpRequest()
  respondToHttpRequest({
    body: readIdentity({}),
    requestId: request.requestId,
  })
})

Coordination operators create child contexts, so contextId can change as work progresses. Don’t use it as a correlation key; use correlationId or a provider ID.

Built-in triggers

Built-in actions

Runtime utilities

Integrations

`getNextHookLocation`

`getAutomationExecutionIdentity`

​getNextHookLocation

​getAutomationExecutionIdentity

`getNextHookLocation`

`getAutomationExecutionIdentity`