Components

The SDK provides five Web Components. Each renders inside Shadow DOM, isolated from your host page styles.

<hyphen-task-sidebar>

A sidebar panel showing pending human-in-the-loop tasks from your workflows. Each task displays the workflow name, step context, urgency level, and approve/reject controls.

<hyphen-task-sidebar
  auto-refresh
  refresh-interval="10000"
  show-urgency>
</hyphen-task-sidebar>

Attributes

Events

How It Works

The sidebar fetches pending tasks scoped to your publishable key. When a user clicks approve or reject, the SDK sends the decision to the gateway, which forwards it to the workflow engine. The workflow resumes from the approval step with the decision in context (@__approved, @__comment).

<hyphen-data-grid>

A sortable, paginated data table connected to Hyphen custom tables. Supports inline editing for operations teams.

<hyphen-data-grid
  table="invoices"
  page-size="25"
  editable
  highlight-agent>
</hyphen-data-grid>

Attributes

Events

Inline Editing

When editable is set, users can double-click any cell to edit its value:

• Enter saves the change
• Escape cancels the edit
• Blur (clicking away) saves automatically

Edits are sent as PATCH requests to the gateway, which updates the custom table and logs the change in the audit trail. The authenticated user's identity is attached to every edit.

Status Pill Detection

The data grid automatically detects status columns (by column name or known value patterns) and renders values as colored pills:

<hyphen-doc-feed>

A document management surface with upload capabilities. Shows existing documents for the configured workflow, their processing status, and provides a compact upload bar for new files.

<hyphen-doc-feed
  workflow-id="wf_invoice_processing"
  accept=".pdf,.csv,.xlsx"
  max-size="52428800"
  multiple>
</hyphen-doc-feed>

Attributes

Events

How It Works

1. User uploads a file via the upload bar
2. The SDK sends the file to the document storage API
3. If workflow-id is set, the SDK triggers the workflow with the document reference as input
4. The feed shows the document's processing status in real time (queued, processing, completed, failed)

Documents display with file type icons (PDF, CSV, XLSX) and their trigger status. Each document links to its associated workflow run.

<hyphen-auth-modal>

An OTP-based login modal for pre-registered team members. Handles the full email + 8-digit code verification flow.

<script>
  // Show the login modal
  sdk.login();
</script>

The auth modal is not placed in HTML directly — it's triggered programmatically via sdk.login(). The modal renders as a fullscreen overlay with three steps:

1. Email entry — user enters their registered email address
2. OTP verification — user enters the 8-digit code sent to their email
3. Success confirmation — brief confirmation before the modal auto-closes

Events

Session Upgrade

On successful authentication, the SDK upgrades the session from anonymous to authenticated. All components automatically reflect user-level permissions — the task sidebar may show additional tasks, and the data grid may enable editing that was previously restricted.

<hyphen-agent-console>

A full agent launch, monitoring, and results console. Lets operations teams run ReAct agents by writing an objective, selecting tools, and watching the reasoning trace in real time.

<hyphen-agent-console
  max-iterations="15"
  show-trace
  poll-interval="3000">
</hyphen-agent-console>

Attributes

Events

Three Modes

Launch — The user writes an objective, optionally attaches files (PDF, CSV, etc.), selects tools from registered actions and workflows, and configures max iterations. Clicking "Launch Agent" uploads any files and executes the agent asynchronously.

Monitor — A vertical animated timeline shows each reasoning step as it happens:

• Completed steps display with a checkmark and the action name
• The active step shows an animated spinner
• Click any step to expand the full thought and observation

The monitor also handles paused agents — when the agent requests human input, a resume section appears with approve/reject controls.

Result — Shows the final answer, confidence score, any triggered workflow runs, and the full reasoning trace. If the run used previous-run-id, the result view displays the linked prior run. A "New Agent" button resets back to launch mode.

Cross-Run Context

Agents can reference a prior run's outcome. Set previous-run-id to a completed agent run ID, and the new agent receives the prior run's objective, final answer, status, and a condensed reasoning trace as context in its system prompt.

This enables multi-stage workflows where one agent's conclusion feeds into the next — without re-executing the prior work. The engine validates org ownership of the referenced run, so cross-org references are rejected.

<hyphen-agent-console
  previous-run-id="agent-abc123"
  show-trace>
</hyphen-agent-console>

Or via the API:

{
  "objective": "Review the findings from the prior audit and recommend next steps",
  "tools": ["act_reviewer"],
  "previous_run_id": "agent-abc123"
}

How It Works

The agent console uses the same scoped authentication as all SDK components. Tools available in the picker are filtered to the publishable key's allowed_actions and allowed_workflows. The gateway validates tool access before proxying to the execution engine.

Combining Components

Components work together through the SDK's event system. When a document is uploaded via <hyphen-doc-feed>, the triggered workflow may create approval tasks that appear in <hyphen-task-sidebar>. Approved tasks may update rows in <hyphen-data-grid>.

<div style="display: flex; height: 100vh;">
  <hyphen-task-sidebar auto-refresh show-urgency
    style="width: 360px;">
  </hyphen-task-sidebar>

  <div style="flex: 1; padding: 24px;">
    <hyphen-data-grid table="invoices" editable>
    </hyphen-data-grid>

    <hyphen-doc-feed workflow-id="wf_invoice_processing"
      accept=".csv,.pdf" style="margin-top: 24px;">
    </hyphen-doc-feed>
  </div>
</div>

All components share the same SDK instance and session. Events from one component are visible to others via sdk.on().