algen-agent-runtime 0.1.0a1__tar.gz

algen_agent_runtime-0.1.0a1/.agents/skills/algen-agent-builder/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: algen-agent-builder
+description: Create or update an Algen-compatible single-agent or multi-agent project that uses Runtime manifests, governance, tests, and Studio-importable packaging.
+---
+
+# Build an Algen agent project
+
+Start by choosing the smallest topology that fits: one agent for a single governed conversation, or
+a Runtime `WorkflowManifest` for coordination. Read `references/project-shape.md`; for a workflow,
+also read `references/workflows.md`. Use `$algen-agent-connector` when external tools, databases,
+retrieval, MCP, or remote APIs are part of the request.
+
+Prefer configuration for provider routing, policies, memory, retrieval, storage, telemetry, and
+workflow topology. Keep only domain-specific payload builders, validators, schemas, predicates, and
+deterministic handlers in the project's hook provider. Never implement a second scheduler or a
+Studio-specific workflow dialect.
+
+Produce an importable project with secret references, bounded execution, deterministic offline
+tests, documented optional dependencies, and a small runnable entry point. A project intended for
+Studio must keep its Runtime configuration and `WorkflowManifest` authoritative; Studio discovers
+and runs that same contract.
+
+Validate YAML by loading it through the current Runtime model rather than relying on syntax alone.
+Run the project smoke test and relevant Runtime tests. Do not publish to a marketplace or deploy
+unless the user explicitly requests that external action.
+

algen_agent_runtime-0.1.0a1/.agents/skills/algen-agent-builder/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Algen Agent Builder"
+  short_description: "Build Runtime-native agents and DAG workflows"
+  brand_color: "#8B5CF6"
+  default_prompt: "Use $algen-agent-builder to create a Studio-importable agent project for this use case."
+

algen_agent_runtime-0.1.0a1/.agents/skills/algen-agent-builder/references/project-shape.md

@@ -0,0 +1,39 @@
+# Agent project shape
+
+A portable project normally contains:
+
+```text
+my_agent/
+├── __init__.py
+├── agent.yaml          # providers, agents, workflows, retrieval, stores, telemetry
+├── app.py              # small local entry point using Runtime APIs
+├── hooks.py            # only when a workflow needs domain hooks
+├── manifest.yaml       # catalogue metadata for examples/marketplace tooling
+├── README.md
+└── tests/
+    └── test_smoke.py
+```
+
+Larger applications may put `agent.yaml` under `config/`. Keep the package import path stable so a
+workflow `hook_provider: my_agent.hooks:create_hooks` can be loaded after installation.
+
+## Single-agent baseline
+
+- Declare at least one provider and agent in `agent.yaml`.
+- Use `env://NAME` for credentials and DSNs.
+- Bound `max_steps`, latency, tokens, cost, retries, and memory retention.
+- Enable only the tools and permissions the agent needs.
+- Choose guardrails, verification, approvals, and model allowlists based on actual risk.
+- Use in-memory stores for examples; document PostgreSQL/Redis settings for durable deployments.
+
+Use `examples/quickstart_cloud_chat`, `quickstart_local_chat`, `quickstart_rag`, and
+`pattern_text_to_sql` as current working references. Copy concepts, not stale versions of internal
+classes.
+
+## Importability
+
+The project configuration—not Studio metadata—is the source of truth. Browser-folder import uploads
+configuration but not executable Python; hook-based projects must also be installed into Studio's
+Python environment or imported from a trusted server-visible source. Git imports likewise do not
+auto-install untrusted code.
+

algen_agent_runtime-0.1.0a1/.agents/skills/algen-agent-builder/references/workflows.md

@@ -0,0 +1,74 @@
+# Runtime multi-agent workflows
+
+Use a `WorkflowManifest` under the top-level `workflows` mapping. Choose nodes deliberately:
+
+- `agent`: one bounded agent run;
+- `map_agent`: bounded dynamic fan-out over a runtime list;
+- `handler`: deterministic domain operation registered by a hook provider;
+- `predicate`: declarative branch condition;
+- `join`: merge dependency outputs using `concat`, `json_array`, or `first`;
+- `approval`: durable approve/modify/reject checkpoint owned by Runtime;
+- `workflow`: dispatch one exact, registered child workflow version with typed input and canonical
+  output.
+
+Declare `input_schema` when a workflow accepts more than one value or anything more structured than
+legacy free text. Use JSON Schema Draft 2020-12, keep the payload secret-free, and read it from
+`WorkflowHookContext.state.values["inputs"]`. Declare `output_schema` together with `output_key` when
+callers depend on a canonical typed result. Runtime validates both contracts; Studio renders the same
+input schema and must not replace it with Studio-specific form metadata.
+
+Represent file, image, or audio inputs as artifact IDs, not base64 or local paths. Use a string schema
+with `format: artifact` and, when known, `contentMediaType`. The host stages the file through the
+Runtime artifact lifecycle; hooks must resolve it in the current tenant and reject expired,
+quarantined, mismatched-media-type, or oversized content.
+
+Do not mark uploads available from a workflow hook. A deployment-owned `ArtifactScanner` must run
+through `ArtifactLifecycleService` first; workflows consume only `available` descriptors and should
+record artifact IDs—not object keys or presigned URLs—in their typed state.
+
+For typed execution, pass `{"inputs": payload}` as the executor's initial values. Do not add
+clarification history, credentials, or host bookkeeping to the typed payload; those belong in
+separate workflow state keys.
+
+Express edges only with `depends_on`. Use `run_if` for conditional execution, `pause` for bounded
+clarification or human input, `max_repairs` plus a validator for structured-output repair,
+`max_iterations` plus `loop_until` for bounded loops, and `failure_policy` for explicit failure
+semantics. Choose `recovery_policy` explicitly: keep the fail-closed default for side effects and use
+`retry` only when replay is idempotent or externally reconcilable. Cap workflow concurrency, timeout,
+and map fan-out.
+
+Use a first-class `approval` node—not a clarification predicate—before consequential work. Declare a
+clear prompt, only deliberately reviewable `review_from` paths, optional secret-free parameters and
+their JSON Schema, a bounded expiry, and whether modification is permitted. Keep the defaults
+`allow_modification: false` and `rejection_policy: skip_dependents`; use `continue` only for a branch
+designed to consume a rejection.
+Resume it with `executor.decide_approval`, passing the authenticated reviewer identity. Treat
+approval parameters and review context as persisted operator-visible data: never include credentials,
+presigned URLs, unrestricted model context, or raw private artifacts.
+
+Use `storage.workflow_store: postgres` outside local development. Resume a clarification with
+`executor.resume`; never invoke `run` again because that creates a new workflow and replays completed
+predecessors. At host startup, list recoverable Runtime checkpoints, reconstruct only trusted hook
+providers, and call `executor.recover` with the exact versioned manifest.
+
+For composition, register every trusted child manifest and its hooks in a `WorkflowRegistry`, then
+give that registry to the parent executor. A `workflow` node must pin `workflow_name` and
+`workflow_version`; never resolve a floating latest version. Runtime owns correlation and lineage,
+child checkpoint identity, depth and cycle limits, clarification/approval propagation, recovery, and
+canonical output validation. Parent concurrency bounds whole child executions. Runtime checkpoints
+the child ID and input before dispatch so recovery either reconciles that child or creates the same
+recorded identity after a pre-creation crash. Resume or decide through the parent checkpoint. Do not
+invoke the child directly or copy its nodes into the parent. Child inputs and outputs must be
+JSON-compatible and secret-free. See `examples/pattern_child_workflow`.
+
+Declare tools, query sources, retrieval, memory, storage, cache, telemetry, and services in each
+node's `resources`. These references are secret-free operational topology and allow Studio to draw
+the real dependency graph.
+
+The hook factory returns `WorkflowHookRegistry`. Register only names referenced by the manifest:
+builders, validators, schemas, and deterministic handlers. Runtime owns scheduling, run state,
+events, repair, clarification, resume, failure propagation, and cancellation.
+
+Use `examples/pattern_multi_agent_fanout`, `pattern_approval_workflow`,
+`pattern_child_workflow`, `pattern_governed_research`, and the reference applications as current
+examples.

algen_agent_runtime-0.1.0a1/.agents/skills/algen-agent-connector/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: algen-agent-connector
+description: Connect an Algen Runtime agent or workflow to typed tools, MCP, HTTP APIs, databases, retrieval stores, model providers, memory, persistence, or telemetry without bypassing governance.
+---
+
+# Connect an Algen agent
+
+Identify the requested systems, data direction, side effects, credentials, network boundary,
+tenancy, and expected failure behavior. Read the matching parts of `references/connectors.md` and
+combine connectors only when the use case needs them.
+
+Expose external actions as typed Runtime tools or workflow resources. Do not call a connector
+directly from orchestration code to bypass policy, approvals, idempotency, audit events, budgets, or
+telemetry. Use secret references in configuration and resolve values only at execution time.
+
+For each connection, declare least-privilege permissions, read/write behavior, idempotency, strict
+schemas, timeout, retry policy, concurrency, result-size limit, and allowed destinations. Mark it on
+the consuming workflow node with a `WorkflowResourceReference` so Studio can display the actual
+topology.
+
+Test with a deterministic fake or local fixture. Live credentials and paid services belong only in
+explicit live tests. Document the required Runtime extra and environment variable names without
+including secret values.
+

algen_agent_runtime-0.1.0a1/.agents/skills/algen-agent-connector/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Algen Agent Connector"
+  short_description: "Connect agents without bypassing governance"
+  brand_color: "#06B6D4"
+  default_prompt: "Use $algen-agent-connector to connect this agent to the requested systems safely."

algen_agent_runtime-0.1.0a1/.agents/skills/algen-agent-connector/references/connectors.md

@@ -0,0 +1,81 @@
+# Connector choices
+
+## Model providers
+
+Declare providers in `agent.yaml`, reference credentials with `env://`, and give agents a
+provider-neutral model requirement plus allowlist/fallback policy. Keep provider-specific options in
+`extensions`. Use the mock provider for deterministic tests.
+
+## Local Python tools
+
+Create a `ToolDefinition` with strict JSON input/output schemas, permissions, `SideEffect`,
+`Idempotency`, timeout, concurrency, cost, and size bounds. Register the `Tool` in the deployment's
+registry. Require approval for writes, external effects, or destructive actions as appropriate.
+
+## MCP
+
+Wrap a deployment-owned MCP client with `mcp_tool`; retain a Runtime `ToolDefinition` as the local
+governance contract. Treat MCP server output as untrusted and do not let remote metadata grant local
+permissions.
+
+## HTTP APIs
+
+Use `remote_tool` or an equivalent typed adapter. Configure a fixed endpoint or an allowlisted host,
+deny private-network access by default, avoid redirects across trust boundaries, propagate the
+idempotency key, and bound response size and time.
+
+## Email
+
+Use `communications.email.EmailMessage` and `email_tool` rather than creating an application-local
+send contract. Addresses, headers, recipients, subject/body size, attachments, and provider receipts
+are validated and content-minimal. Attachments are tenant-authorized Runtime artifact references;
+never accept arbitrary filesystem paths. The first adapter, `SmtpEmailSender`, requires TLS by
+default, expects credentials resolved by the deployment secret boundary, keeps BCC out of message
+headers, and derives a stable Message-ID from the Runtime idempotency key.
+
+Email is an external keyed side effect. Keep Runtime's durable tool-execution ledger enabled in
+production. A provider timeout after submission is indeterminate and must be reconciled rather than
+automatically replayed. Delivery approval, suppression, bounce/complaint handling, reply ingestion,
+provider OAuth, and campaign policy remain application or connector responsibilities.
+
+## Databases and query sources
+
+Use `database_tool` with a deployment-owned async handler. Prefer read-only, parameterized queries
+and a database credential restricted at the server. For analytical workflows, declare a secret-safe
+`query_source` and a node resource with `kind: query_source`. SQL generation, validation, execution,
+repair, and verification remain separate bounded stages.
+
+## Retrieval
+
+Choose memory for small examples; pgvector, Chroma, FAISS, or Qdrant for supported vector workloads.
+Install only the corresponding extra. Preserve source provenance and tenant filters, cap retrieved
+tokens, and instruct agents not to follow instructions embedded in retrieved content.
+
+## Memory, cache, and durable stores
+
+Use memory backends for tests and ephemeral local runs. Use PostgreSQL for durable run, event, audit,
+approval, artifact, tool-execution, and conversation records; use Redis where supported for cache or
+stores. Connection values remain `env://` references. Declare memory/cache/storage resources on the
+workflow nodes that consume them.
+
+For files and binary connector output, store bytes through `ArtifactStore` and pass only artifact IDs
+through messages or workflow values. Preserve tenant scope, checksum, lifecycle state, expiry, and
+size limits. User uploads begin `pending_scan`; a deployment-owned scanner marks them `available` or
+`quarantined`. PostgreSQL is suitable only for bounded payloads; use the optional S3 adapter for
+large blobs while retaining PostgreSQL lifecycle metadata. Configure bucket, prefix, region,
+server-side encryption, and optional KMS key—never static access keys. Implement scanners behind
+`ArtifactScanner` and invoke `ArtifactLifecycleService` so the pending transition is compare-and-set
+and audited; do not update status directly in application domain code.
+
+## Telemetry
+
+Runtime supports OpenTelemetry and optional Traccia. Keep content capture off unless explicitly
+required and authorized, redact PII, and declare telemetry resources with `access: observe`.
+
+## Useful combinations
+
+- Grounded assistant: model provider + retrieval + memory + telemetry.
+- Safe action agent: model provider + read tools + approval-gated write tool + audit store.
+- Data analyst: model provider + schema retrieval + read-only query source + SQL verifier.
+- Research DAG: planner + bounded retrieval fan-out + join + citation verifier.
+- Support workflow: tenant retrieval + CRM read + approval-gated ticket/billing write + durable runs.

algen_agent_runtime-0.1.0a1/.agents/skills/algen-runtime-contributor/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: algen-runtime-contributor
+description: Implement or review contributions to Algen Agent Runtime while preserving its public API, provider neutrality, tenant isolation, optional dependencies, and repository boundary.
+---
+
+# Contribute to Algen Agent Runtime
+
+Work from the Runtime repository root. Read `CONTRIBUTING.md` and the documentation most closely
+related to the change before editing. Use `references/change-checklist.md` when planning or reviewing
+a code change.
+
+Keep reusable execution contracts, orchestration, governance, persistence, and integrations in
+Runtime. Keep Studio UI, project management, marketplace, and product-specific behavior out of this
+repository. Domain behavior belongs in an application hook provider, not in the Runtime executor.
+
+Preserve these invariants:
+
+- provider-neutral public contracts and typed boundaries;
+- explicit tenant, user, permission, secret, and idempotency context;
+- deterministic offline behavior and tests by default;
+- optional provider, database, vector-store, telemetry, and framework dependencies;
+- stable error codes and forward migrations for persisted data;
+- secret-free configuration committed to source control.
+
+Add the narrowest meaningful test and cover the relevant failure path. Update public documentation,
+examples, and `CHANGELOG.md` for user-visible behavior. Run the repository quality gates before
+finishing; report any gate that could not run and why. Do not commit, push, publish, or open a pull
+request unless the user explicitly requests it.
+

algen_agent_runtime-0.1.0a1/.agents/skills/algen-runtime-contributor/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Algen Runtime Contributor"
+  short_description: "Build safe, compatible Runtime contributions"
+  brand_color: "#4F46E5"
+  default_prompt: "Use $algen-runtime-contributor to implement this Runtime change with tests and compatibility checks."
+

algen_agent_runtime-0.1.0a1/.agents/skills/algen-runtime-contributor/references/change-checklist.md

@@ -0,0 +1,59 @@
+# Runtime change checklist
+
+Use the applicable sections; do not force irrelevant work into a small change.
+
+## Boundary and compatibility
+
+- Is this a reusable Runtime capability rather than Studio or marketplace behavior?
+- Does it change a public import, YAML contract, event, error code, or persisted schema?
+- If it changes `WorkflowManifest`, are manifest validation, execution validation, Studio
+  consumption, examples, agent-builder guidance, and the changelog updated together?
+- If compatibility changes, is there an upgrade note, migration path, and changelog entry?
+- For durable workflows, are tenant isolation, optimistic version conflicts, manifest fingerprints,
+  pause/resume, deadline suspension, recovery opt-in, and interrupted side effects tested?
+- For workflow approvals, are authenticated reviewer identity, approve/modify/reject outcomes,
+  parameter-schema validation, expiry, rejection propagation, checkpoint durability, event-content
+  minimization, and invalid-decision deadline behavior tested?
+- For child workflows, are exact-version registry resolution, typed input/canonical output,
+  correlation and lineage, cycle/depth limits, nested pause/decision propagation, checkpoint-first
+  dispatch, bounded parent concurrency, pre-child-creation failure, and recovery without duplicate
+  children tested?
+- Does core remain usable without a new optional integration installed?
+- For artifact changes, are staged pre-run inputs, checksums, lifecycle state, expiry, tenant-scoped
+  list/read/delete, PostgreSQL migration, and large-object boundaries covered?
+- For object storage, are partial failure compensation, retry-safe deletion, encryption, checksum
+  verification, opaque tenant keys, credential discovery, scanner compare-and-set, and audit evidence
+  covered without requiring the optional SDK in core installs?
+- For email changes, are header injection, recipient and attachment bounds, BCC privacy, TLS,
+  artifact-only attachments, stable idempotency, content-minimal receipts/errors, provider refusal,
+  and ambiguous delivery failure tested?
+
+## Security and operations
+
+- Preserve tenant isolation and authorization at every read and write boundary.
+- Resolve secrets through `env://` or `secret://`; never serialize values into manifests or events.
+- Classify tool side effects and idempotency accurately.
+- Default interrupted workflow nodes to fail closed; never infer retry safety from node kind alone.
+- Bound retries, repairs, loops, fan-out, payload sizes, concurrency, and network access.
+- Avoid telemetry content by default; redact credentials and sensitive payloads.
+- Keep workflow approval review paths and parameters explicitly secret-free; approval events must not
+  expose review values, parameters, or operator comments.
+
+## Evidence
+
+- Unit tests: deterministic contracts and failure behavior.
+- Contract tests: provider, tool, store, retrieval, or framework compatibility.
+- Integration tests: several Runtime components working together.
+- End-to-end tests: public API or representative application path.
+- Paid or networked checks use the `live` marker and are never required for ordinary pull requests.
+
+## Quality gates
+
+```bash
+ruff format --check src tests examples
+ruff check src tests examples
+mypy src/algen_agent_runtime
+pytest -q -p no:cacheprovider
+```
+
+Use `make lint`, `make typecheck`, and `make test` when the Makefile is the better local entry point.

algen_agent_runtime-0.1.0a1/.agents/skills/algen-runtime-extension/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: algen-runtime-extension
+description: Add or review an Algen Agent Runtime extension such as a model provider, tool adapter, retrieval backend, persistence store, telemetry integration, or external-framework adapter.
+---
+
+# Extend Algen Agent Runtime
+
+First identify the extension point and inspect its Protocol, registry, existing adapter, contract
+tests, optional extra, and documentation. Read only the matching section of
+`references/extension-points.md`.
+
+Implement against Runtime contracts rather than leaking a vendor SDK into orchestration or public
+state. Normalize vendor inputs, outputs, usage, errors, streaming behavior, and cancellation at the
+adapter boundary. Keep the dependency optional and fail with an actionable installation message
+when its extra is absent.
+
+Treat all extension inputs as untrusted. Carry tenant and identity context, enforce permissions,
+validate outbound destinations, classify side effects and idempotency, bound time and result size,
+and prevent secrets from entering logs or persisted events.
+
+Add deterministic contract tests without credentials. Put live integration tests behind the `live`
+marker. Update the optional dependency extra, compatibility documentation, an importable example
+when useful, and `CHANGELOG.md` for user-visible support.
+

algen_agent_runtime-0.1.0a1/.agents/skills/algen-runtime-extension/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Algen Runtime Extension"
+  short_description: "Add providers, stores, tools, and adapters"
+  brand_color: "#0EA5E9"
+  default_prompt: "Use $algen-runtime-extension to add this integration behind Runtime contracts and deterministic tests."
+

algen_agent_runtime-0.1.0a1/.agents/skills/algen-runtime-extension/references/extension-points.md

@@ -0,0 +1,62 @@
+# Runtime extension points
+
+## Model provider
+
+Inspect `src/algen_agent_runtime/models/providers/`, the provider registry, and provider contract
+tests. Normalize messages, tool calls, structured output, streaming, usage, retryable failures, and
+capabilities. Provider credentials remain secret references. Document supported capabilities and
+known limitations in `docs/provider-compatibility.md`.
+
+Provider-specific strict JSON Schema subsets belong at the provider boundary. Preserve the original
+application schema for Runtime validation; translate only the wire copy and cover nested objects,
+optional/defaulted fields, constants, and unsupported constraint keywords in contract tests.
+
+## Tool or connector adapter
+
+Inspect `tools/contracts.py`, `tools/adapters.py`, the executor, and policy engine. Every tool needs a
+strict input schema, output schema, permissions, side-effect class, idempotency class, timeout,
+concurrency bound, and result-size bound. Use `ToolContext` for identity and secrets. A database
+connector accepts parameterized statements through a deployment-owned handler; remote HTTP tools
+must validate destinations and propagate the idempotency key.
+
+Email provider adapters implement `communications.email.EmailSender` and return the normalized,
+content-minimal `EmailDeliveryReceipt`. Preserve the supplied idempotency key as the provider's
+deduplication key or stable message identifier. Validate provider recipient refusals explicitly,
+resolve attachments only through a tenant-authorized artifact loader, do not leak message bodies or
+credentials in exceptions, and treat an uncertain post-submission failure as indeterminate through
+the Runtime tool ledger. See `docs/email.md`.
+
+## Retrieval backend
+
+Inspect `retrieval/contracts.py`, `retrieval/vector_stores.py`, and `docs/rag.md`. Preserve tenant
+filters, source provenance, score semantics, query/context limits, and prompt-injection boundaries.
+Keep the backend SDK behind an optional extra.
+
+## Persistence store
+
+Inspect the relevant Protocol and in-memory/PostgreSQL implementations. Preserve tenant-scoped keys,
+atomic state transitions, optimistic concurrency where defined, timestamps, recovery behavior, and
+forward schema migrations.
+
+Workflow checkpoint stores additionally require detached reads, tenant isolation, compare-and-set
+versions, manifest fingerprints, recoverable-state filtering, and corruption failure behavior. Run
+the shared in-memory/PostgreSQL conformance suite when adding another backend. Parent/child workflow
+recovery must reconcile the recorded child checkpoint; it must never dispatch a replacement child.
+
+Artifact stores additionally preserve optional run association, content checksum and length,
+scan/quarantine status, metadata-only reads, expiry visibility, bounded purge, and permanent
+tenant-scoped deletion. Keep large-object SDKs optional and never return another tenant's descriptor
+or bytes.
+
+For S3-compatible implementations, keep authoritative metadata in a tenant-scoped durable store,
+hash tenant identifiers in object keys, request service-side checksums and encryption, conditionally
+create objects, verify downloads locally, compensate partial uploads, and make deletion/expiry safe
+to retry. Credentials come from workload identity or the SDK chain, not Runtime YAML. Scanner
+adapters return only `ArtifactScanResult`; lifecycle state and audit writes belong to
+`ArtifactLifecycleService`.
+
+## Framework or telemetry adapter
+
+Inspect `docs/framework-adapters.md` or `observability/`. Runtime remains the governance envelope;
+framework-native state must not bypass identity, policy, budgets, tool execution, or normalized
+events. Telemetry integrations must remain optional and must not include content by default.

algen_agent_runtime-0.1.0a1/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.env
+.DS_Store

algen_agent_runtime-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to Algen Agent Runtime will be documented in this file.
+The project follows [Semantic Versioning](https://semver.org/) while public
+contracts are explicitly marked experimental during the `0.x` series.
+
+## [Unreleased]
+
+_No unreleased changes yet._
+
+---
+
+## [0.1.0a1] - 2026-09-22
+
+First public alpha. Intended for evaluation and contribution; not a
+production-readiness claim. Contracts labelled `experimental` may change
+without a deprecation window during the `0.x` series.
+
+### Added
+
+- Repository-scoped contributor, extension, agent-building, and connector skills for coding agents.
+- A shared Algen ecosystem identity with light/dark Runtime logo and README banner assets, plus
+  documented Runtime, Studio, and Marketplace product boundaries.
+- Studio-importable Runtime examples shipped with their Python hook providers and configuration in
+  source and wheel distributions.
+- Runnable cloud chat, typed capability, human checkpoint, governed research, LangGraph adapter,
+  multi-agent fan-out, evaluation gate, customer support, incident response, and invoice exception
+  examples.
+- Runtime DAG manifests for the responsible hiring and teaching-assistant case studies.
+- Deterministic configuration, hook-loading, workflow execution, and checkpoint regression coverage
+  for the example portfolio.
+- Initial open-source governance, security, contribution, and release policies.
+- PyPI metadata, deterministic build contents, and clean-install CI checks.
+- Public-ready README with an offline quickstart, support matrix, architecture overview, and
+  security boundaries.
+- API stability and release-process documentation.
+- Dedicated PyPI Trusted Publishing, CodeQL, and pull-request dependency-review workflows.
+- Separation of the private Algen Agent Studio application from the Runtime distribution.
+- Runtime-owned multi-agent workflow manifests and an embedded DAG executor with agent and
+  deterministic-handler nodes, conditional execution, clarification limits, bounded validation
+  repair, capped dynamic fan-out, correlated child runs, and lifecycle events.
+- Application hook registries for workflow payloads, request metadata, structured-output schemas,
+  domain validation, and deterministic service execution.
+- Runtime predicate and join nodes, declarative input templates, bounded agent loops, deterministic
+  ready-node ordering, conditional-branch convergence, host-provided agent execution, and portable
+  application hook-provider references.
+- Typed, secret-free workflow resource references for documenting node connections to tools, query
+  sources, retrieval indexes, memory, caches, stores, telemetry, and application services.
+- Runtime-owned JSON Schema Draft 2020-12 workflow input and canonical-output contracts with
+  manifest-time schema checks and fail-closed execution validation.
+- Tenant-scoped staged artifacts with optional run association, SHA-256 and size metadata,
+  scan/available/quarantine states, expiry, metadata listing, deletion, bounded purge, HTTP lifecycle
+  endpoints, and a forward PostgreSQL migration.
+- Optional PostgreSQL-metadata/S3-blob artifact storage with server-side encryption, service-side
+  SHA-256 checks, tenant-hashed keys, conditional creation, compensating cleanup, health checks, and
+  an audited compare-and-set `ArtifactScanner` lifecycle service.
+- Runtime-owned in-memory and PostgreSQL multi-agent workflow checkpoint stores with tenant isolation,
+  optimistic versions, manifest fingerprints, pause/resume without completed-node replay, suspended
+  human-wait deadlines, and explicit fail-closed or retry crash recovery.
+- First-class Runtime workflow approval nodes with durable approve/modify/reject decisions,
+  authenticated reviewer attribution, schema-validated parameter modification, bounded expiry,
+  safe rejection propagation, and content-minimal lifecycle events.
+- Exact-version parent/child workflow composition with a trusted registry, typed child input and
+  canonical output, lineage, cycle/depth guards, nested clarification and approval propagation, and
+  checkpoint-first recovery without duplicate child dispatch.
+- Provider-neutral, validated email contracts and a TLS-first SMTP adapter exposed as an
+  idempotency-aware Runtime tool with artifact-only attachments and content-minimal receipts.
+- Shared workflow checkpoint-store conformance coverage plus corruption, ambiguous email delivery,
+  and parent/child crash-recovery failure-injection tests.
+- Updated the responsible-hiring, customer-support, incident-response, and invoice-exception
+  reference workflows to use first-class Runtime approvals and explicit recovery safety instead of
+  clarification-shaped action checkpoints.
+- DAG-based multi-agent workflow engine (`MultiAgentWorkflowExecutor`) with full topological
+  scheduling, fan-out/fan-in, conditional branching, and error recovery.
+- Durable execution via in-memory and PostgreSQL checkpoint persistence backends.
+- Extended `WorkflowManifest` and contracts with typed node, edge, and dependency schemas.
+- OpenAI-compatible model provider adapter and provider contract test suite.
+- Approval workflow patterns (`pattern_approval_workflow`, `quickstart_approval`) with
+  human-in-the-loop hooks.
+- Fixed stale module references and CLI run commands across all example packages.
+- Enhanced responsible-hiring case-study UI dashboard.
+- Normalize OpenAI and Azure OpenAI response schemas at the provider boundary for strict structured
+  outputs: all object fields are required, additional properties are forbidden, and defaults and
+  unsupported wire constraints are removed while Runtime retains full result validation.
+
+[Unreleased]: https://github.com/AlgenAI/algen-agent-runtime/compare/v0.1.0a1...HEAD
+[0.1.0a1]: https://github.com/AlgenAI/algen-agent-runtime/releases/tag/v0.1.0a1