> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Objectives, Webhooks, and Event Triggers

<details>
  <summary>Relevant source files</summary>

  The following files were used as context for generating this wiki page:

  * crates/palyra-cli/src/args/commitments.rs
  * crates/palyra-cli/src/args/ids.rs
  * crates/palyra-cli/src/args/objectives.rs
  * crates/palyra-cli/src/args/tasks.rs
  * crates/palyra-cli/src/commands/commitments.rs
  * crates/palyra-cli/src/commands/objectives.rs
  * crates/palyra-cli/src/commands/tasks.rs
  * crates/palyra-cli/tests/help\_snapshots/commitments-help.txt
  * crates/palyra-cli/tests/help\_snapshots/cron-delete-help.txt
  * crates/palyra-cli/tests/help\_snapshots/cron-logs-help.txt
  * crates/palyra-cli/tests/help\_snapshots/objectives-upsert-help.txt
  * crates/palyra-cli/tests/help\_snapshots/routines-create-from-template-help.txt
  * crates/palyra-cli/tests/help\_snapshots/routines-delete-help.txt
  * crates/palyra-cli/tests/help\_snapshots/routines-import-help.txt
  * crates/palyra-cli/tests/help\_snapshots/routines-logs-help.txt
  * crates/palyra-daemon/src/acceptance.rs
  * crates/palyra-daemon/src/application/channel\_commands/mod.rs
  * crates/palyra-daemon/src/application/conversation\_bindings/mod.rs
  * crates/palyra-daemon/src/application/inbound\_coalescer/mod.rs
  * crates/palyra-daemon/src/application/outbound\_lifecycle/mod.rs
  * crates/palyra-daemon/src/commitments.rs
  * crates/palyra-daemon/src/flows.rs
  * crates/palyra-daemon/src/gateway/common.rs
  * crates/palyra-daemon/src/objectives.rs
  * crates/palyra-daemon/src/task\_runtime.rs
  * crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs
  * crates/palyra-daemon/src/transport/http/handlers/admin/channels/message\_mutations.rs
  * crates/palyra-daemon/src/transport/http/handlers/admin/skills.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/commitments.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/objectives.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/tasks.rs
  * crates/palyra-daemon/src/webhooks.rs
</details>

The Palyra automation layer provides a system for tracking long-lived operator goals (**Objectives**), ingesting external signals via **Webhooks**, and managing the resulting work through **Flows** and **Commitments**. These subsystems bridge the gap between high-level natural language intent and discrete, scheduled execution units.

## Objectives System

The Objectives system tracks high-level goals that persist across multiple agent runs and sessions. An objective is a durable record that bundles lifecycle state, spend guardrails, and automation bindings [crates/palyra-daemon/src/objectives.rs#1-7](http://crates/palyra-daemon/src/objectives.rs#1-7).

### Objective Lifecycle and Components

Objectives transition through several states: `Draft`, `Active`, `Paused`, `Cancelled`, and `Archived` [crates/palyra-daemon/src/objectives.rs#83-90](http://crates/palyra-daemon/src/objectives.rs#83-90). Each objective is backed by:

1. **The Objective Record**: Stores metadata, priority, and budget [crates/palyra-daemon/src/objectives.rs#3-6](http://crates/palyra-daemon/src/objectives.rs#3-6).
2. **Automation Binding**: Links the objective to a `CronJob` and `Routine` for scheduled execution [crates/palyra-daemon/src/transport/http/handlers/console/objectives.rs#3-5](http://crates/palyra-daemon/src/transport/http/handlers/console/objectives.rs#3-5).
3. **Workspace Projection**: Manages "managed blocks" in workspace documents (e.g., `objective-focus`, `objective-heartbeats`) to provide agents with in-context goals [crates/palyra-daemon/src/transport/http/handlers/console/objectives.rs#5-6](http://crates/palyra-daemon/src/transport/http/handlers/console/objectives.rs#5-6), [crates/palyra-daemon/src/transport/http/handlers/console/objectives.rs#53-55](http://crates/palyra-daemon/src/transport/http/handlers/console/objectives.rs#53-55).

### Objective Judge and Finalization

The system uses an **Objective Judge** to evaluate completion against defined `ObjectiveSuccessCriteria` [crates/palyra-daemon/src/objectives.rs#157-175](http://crates/palyra-daemon/src/objectives.rs#157-175). Finalization can be `ManualReview`, `AutomaticWhenSatisfied`, or `NeverAutomatic` [crates/palyra-daemon/src/objectives.rs#192-197](http://crates/palyra-daemon/src/objectives.rs#192-197).

### Objective Data Flow

The following diagram illustrates how an objective is created and managed through the `console/v1` API.

**Diagram: Objective Lifecycle and Code Entities**

```mermaid theme={null}
sequenceDiagram
    participant Web as "apps/web (Console)"
    participant Hdl as "console/v1/objectives Handler"
    participant Reg as "ObjectiveRegistry"
    participant Cron as "CronStore / RoutineSystem"
    participant WS as "Workspace (Managed Blocks)"

    Web->>Hdl: POST /upsert (ConsoleObjectiveUpsertRequest)
    Hdl->>Reg: upsert_objective(ObjectiveUpsert)
    Reg->>Reg: normalize_record()
    Reg-->>Hdl: ObjectiveRecord
    Hdl->>Cron: sync_objective_automation()
    Hdl->>WS: sync_workspace_managed_block()
    Hdl-->>Web: 200 OK (ObjectiveRecord + Warning Projections)
```

Sources: [crates/palyra-daemon/src/transport/http/handlers/console/objectives.rs#122-190](http://crates/palyra-daemon/src/transport/http/handlers/console/objectives.rs#122-190), [crates/palyra-daemon/src/objectives.rs#1-15](http://crates/palyra-daemon/src/objectives.rs#1-15)

***

## Webhook Ingestion and Replay

The `WebhookRegistry` manages inbound HTTP signals from external providers. It enforces security through HMAC-SHA256 signature verification and single-use replay nonces [crates/palyra-daemon/src/webhooks.rs#1-9](http://crates/palyra-daemon/src/webhooks.rs#1-9).

### Security Gates

1. **Vault Integration**: Signing secrets are never stored in the registry; they are retrieved via `VaultRef` [crates/palyra-daemon/src/webhooks.rs#7-9](http://crates/palyra-daemon/src/webhooks.rs#7-9).
2. **Replay Protection**: `WebhookReplayNonceStore` tracks consumed nonces in an in-memory ledger to prevent duplicate event processing [crates/palyra-daemon/src/webhooks.rs#132-159](http://crates/palyra-daemon/src/webhooks.rs#132-159).
3. **Safety Scan**: All inbound text is inspected by `palyra-safety` for untrusted content before ingestion [crates/palyra-daemon/src/webhooks.rs#25-27](http://crates/palyra-daemon/src/webhooks.rs#25-27).

### Implementation Details

* **Storage**: Integrations are persisted in `webhooks.toml` under the daemon state root [crates/palyra-daemon/src/webhooks.rs#35-36](http://crates/palyra-daemon/src/webhooks.rs#35-36).
* **Verification**: `VaultHmacSha256WebhookVerifier` implements the `WebhookSignatureVerifier` trait [crates/palyra-daemon/src/webhooks.rs#163-179](http://crates/palyra-daemon/src/webhooks.rs#163-179).

Sources: [crates/palyra-daemon/src/webhooks.rs#1-180](http://crates/palyra-daemon/src/webhooks.rs#1-180)

***

## Commitments and Flows Subsystems

The Commitments and Flows subsystems handle the execution of work derived from agent interactions or external triggers.

### Commitments System

Commitments are extracted from user-visible text (explicitly or via inference) and tracked in a ledger [crates/palyra-daemon/src/commitments.rs#1-6](http://crates/palyra-daemon/src/commitments.rs#1-6).

* **Extraction**: `extract_commitments_from_text` splits sentences and uses deterministic heuristics to identify actions, due conditions, and recurrence [crates/palyra-daemon/src/commitments.rs#166-185](http://crates/palyra-daemon/src/commitments.rs#166-185).
* **Review**: Proposed commitments must be reviewed before being bridged to scheduling [crates/palyra-daemon/src/transport/http/handlers/console/commitments.rs#3-5](http://crates/palyra-daemon/src/transport/http/handlers/console/commitments.rs#3-5).

### Flows System

The `FlowCoordinator` manages multi-step execution sequences. It reconciles background tasks, child runs, and approval decisions into a unified flow state [crates/palyra-daemon/src/flows.rs#1-6](http://crates/palyra-daemon/src/flows.rs#1-6).

* **Flow Modes**:
  * `Managed`: Dispatches its own work steps [crates/palyra-daemon/src/flows.rs#50-52](http://crates/palyra-daemon/src/flows.rs#50-52).
  * `Mirrored`: Tracks lineage created by other systems like Routines or Objectives [crates/palyra-daemon/src/flows.rs#51-52](http://crates/palyra-daemon/src/flows.rs#51-52).
* **Lineage**: `FlowLineage` tracks the relationship between a flow step and its originating `session_id`, `run_id`, or `objective_id` [crates/palyra-daemon/src/flows.rs#95-114](http://crates/palyra-daemon/src/flows.rs#95-114).

**Diagram: Commitment to Flow Transition**

```mermaid theme={null}
graph TD
    Text["User Text / Agent Output"] -->|extract_commitments_from_text| Candidate["ExtractedCommitment (Candidate)"]
    Candidate -->|Console Review| Record["CommitmentRecord (Active)"]
    Record -->|Scheduling Bridge| Flow["FlowRecord (Managed)"]
    Flow -->|FlowCoordinator::poll| Step["FlowStepRecord"]
    Step -->|Dispatch| Task["OrchestratorBackgroundTask"]
```

Sources: [crates/palyra-daemon/src/commitments.rs#166-185](http://crates/palyra-daemon/src/commitments.rs#166-185), [crates/palyra-daemon/src/flows.rs#1-35](http://crates/palyra-daemon/src/flows.rs#1-35), [crates/palyra-daemon/src/task\_runtime.rs#51-61](http://crates/palyra-daemon/src/task_runtime.rs#51-61)

***

## Task Runtime and Event Triggers

The `TaskRuntime` provides a unified read model over disparate execution entities, including Background Tasks, Flows, Tool Jobs, WorkBoard items, and Commitments [crates/palyra-daemon/src/task\_runtime.rs#1-5](http://crates/palyra-daemon/src/task_runtime.rs#1-5).

### Unified Task Model

All executable items are normalized into a `TaskSourceKind` [crates/palyra-daemon/src/task\_runtime.rs#51-61](http://crates/palyra-daemon/src/task_runtime.rs#51-61):

| TaskSourceKind   | Role                                         |
| :--------------- | :------------------------------------------- |
| `BackgroundTask` | Single-turn agent execution.                 |
| `Flow`           | Multi-step coordinated sequence.             |
| `ToolJob`        | Long-running tool execution (e.g., browser). |
| `WorkItem`       | Durable item on the operator WorkBoard.      |
| `Commitment`     | Extracted goal awaiting fulfillment.         |

### Event Coalescing

Inbound events from channels (Discord, Slack) are processed by the `InboundCoalescer`. This system debounces rapid-fire messages by bucketizing them based on an `InboundCoalescingKey` (principal, session, channel, etc.) before triggering a provider turn [crates/palyra-daemon/src/application/inbound\_coalescer/mod.rs#1-9](http://crates/palyra-daemon/src/application/inbound_coalescer/mod.rs#1-9), [crates/palyra-daemon/src/application/inbound\_coalescer/mod.rs#34-44](http://crates/palyra-daemon/src/application/inbound_coalescer/mod.rs#34-44).

Sources: [crates/palyra-daemon/src/task\_runtime.rs#1-61](http://crates/palyra-daemon/src/task_runtime.rs#1-61), [crates/palyra-daemon/src/application/inbound\_coalescer/mod.rs#1-115](http://crates/palyra-daemon/src/application/inbound_coalescer/mod.rs#1-115)