Add rfc26 - clarify intent suspension in containers and human retry c…

[nirvanatikku]

RFC-0026: Suspension Propagation & Retry → v0.17.0

Closes the three gaps left open by RFC-0025 (Human-in-the-Loop Intent Suspension):
container propagation rules, human re-notification with escalation ladders, and
upstream suspension error propagation for workflow phases.

---

What's in this PR

Container Propagation Rules (5 normative rules)

• Intent graph — suspended child intent blocks all dependents; parent aggregate
  status becomes suspended_awaiting_input when any child is suspended.
• Portfolio — aggregate gains has_suspended_members / suspended_member_count;
  two new events: portfolio.member_suspended / portfolio.member_resumed.
• Plan / Task — bidirectional mirror: when an intent suspends, its task transitions
  to blocked with blocked_reason: "intent_suspended" and suspended_intent_id;
  plan progress gains suspended_tasks.
• Workflow — downstream phases receive UpstreamIntentSuspendedError at claim
  time; workflow progress gains suspended_phases.
• Deadline — suspension deadline governs expiry and MUST NOT exceed the portfolio
  due_before constraint.

HumanRetryPolicy Dataclass

Re-notification and escalation policy for request_input():

HumanRetryPolicy(
    max_attempts=3,
    interval_seconds=3600,
    strategy="exponential",       # fixed | linear | exponential
    escalation_ladder=[
        EscalationStep(attempt=2, channel_hint="slack", notify_to="manager@co"),
        EscalationStep(attempt=3, channel_hint="sms",   notify_to="+15551234567"),
    ],
    final_fallback_policy="escalate",
)

Serialises via to_dict() / from_dict().

EscalationStep Dataclass

Single escalation rung: attempt, channel_hint, notify_to. Triggers
intent.suspension_escalated event. Backwards-compatible aliases: after_attempt,
channel, notify.

UpstreamIntentSuspendedError

Raised by WorkflowSpec.validate_claim_inputs() when a declared input references an
upstream phase whose intent is suspended_awaiting_input. Carries task_id,
phase_name, suspended_intent_id, expected_resume_at. Subclass of WorkflowError.

Three-Level Policy Cascade

call-site retry_policy
  → BaseAgent.default_human_retry_policy
    → server suspension.default_retry_policy  (GET /api/v1/server/config)

Four New EventType Constants

Constant	Fired when
intent.suspension_renotified	Each re-notification attempt fires
intent.suspension_escalated	An escalation ladder step fires
portfolio.member_suspended	A portfolio member intent suspends
portfolio.member_resumed	A portfolio member intent resumes

---

Cross-RFC Patches

RFC	Patch summary
RFC-0002	Aggregate suspended_awaiting_input status counter; completion-gate clarification
RFC-0007	Portfolio suspension-aware aggregate fields and member_suspended / member_resumed events
RFC-0010	RFC-0026 relationship note (RFC-0010 retries on agent failure; RFC-0026 re-notifies on human non-response — parallel constructs at different layers)
RFC-0012	Task/intent suspension mirror, suspended_tasks plan progress field
RFC-0024	UpstreamIntentSuspendedError at claim time; suspended_phases workflow progress field
RFC-0025	retry_policy on SuspensionRecord; per-attempt timeout_seconds semantics; fallback_policy alias note; extended cross-RFC table

---

New Tests

41 new tests across two existing test files:

• tests/test_hitl.py — HumanRetryPolicy, EscalationStep, SuspensionRecord.retry_policy,
  new EventType constants, request_input signature, BaseAgent.default_human_retry_policy,
  package exports.
• tests/test_workflow_io.py — UpstreamIntentSuspendedError construction, attributes,
  exception hierarchy, package export.

Total: 1052+ tests across 19 test files — all passing.

---

New Package Exports

from openintent import HumanRetryPolicy, EscalationStep, UpstreamIntentSuspendedError

---

Version Bumps

All 7 version manifests updated from 0.16.1 → 0.17.0:

File	Field
pyproject.toml	version
openintent/__init__.py	__version__
mcp-server/package.json	version
mcp-server/src/index.ts	version in server info block
docs/overrides/home.html	hero badge + stats number
mkdocs.yml	announcement banner
docs/rfcs/0026-suspension-container-interaction.md	RFC header

---

Checklist

• RFC document written and merged (docs/rfcs/0026-suspension-container-interaction.md)
• HumanRetryPolicy and EscalationStep dataclasses implemented and exported
• UpstreamIntentSuspendedError implemented and exported
• BaseAgent.default_human_retry_policy class attribute added
• request_input(retry_policy=...) parameter wired up
• Four new EventType constants added
• retry_policy field on SuspensionRecord
• All cross-RFC patches applied
• 41 new tests passing; full suite (1052+) green
• ruff check clean (80 files, 0 issues)
• mkdocs build --strict passes
• All version manifests at 0.17.0
• Both changelogs in sync