Skip to content

roadmap.md

Latest commit

 

History

History
1653 lines (1355 loc) · 78.3 KB

roadmap.md

File metadata and controls

1653 lines (1355 loc) · 78.3 KB
Raw

LightAgent Roadmap

Last updated: 2026-09-14

LightAgent should continue to evolve as a lightweight, low-dependency agent framework rather than a broad replacement for LangChain, LangGraph, CrewAI, or LlamaIndex.

The product direction remains:

Lightweight core + event-sourced Sessions + composable capability Providers + reliable tool execution + unified Policy + safe memory + deterministic workflows + OpenAI-compatible model ecosystem.

Current Status

Completed

  • v0.6.5: Added structured run results, structured streaming events, catchable LightAgent errors, and tool argument validation while keeping legacy agent.run() and stream=True behavior compatible.
  • v0.7.0: Added opt-in trace observability with structured run, model, tool, and error events.
  • v0.7.5: Added initial memory safety and guardrail capabilities through MemoryPolicy and input/tool/output guardrails.
  • v0.8.0: Added LightFlow for deterministic multi-step workflows with DAG dependencies, step output passing, retries, structured results, and flow trace events.
  • Post-v0.8.0 main: Merged PR #56 to persist self.tracetools and document the optional LiteLLM provider.
  • v0.8.1: Added MemoryScope metadata conventions, stricter MemoryPolicy source/scope/agent/trust/confidence filtering, and docs for separating trace events, user memory, self-reflection memory, and LightSwarm delegation state.
  • v0.8.2: Added optional memory write admission hooks, per-run write limits, duplicate write blocking, and trace events for allowed or blocked memory writes.
  • v0.9.0: Added enhanced LightFlow execution controls, JSON checkpointed workflow runs, resume/rerun support, approval nodes, reusable guardrail templates, stronger memory admission controls, and the first lightweight SharedMemoryPool prototype.
  • v0.9.1: Added the first runtime hook layer through HookContext, HookDecision, HookManager, LightAgent(..., hooks=[...]), and LightFlow(hooks=[...]).
  • v0.9.2: Completed core agent lifecycle hooks with after_run, on_error, memory-retrieval hooks, and async-compatible hook execution.
  • v0.9.3: Hardened streaming tool-loop safety with max_tool_iterations and consistent on_error, after_run, and run_end closure.
  • v0.9.4: Released tool schema diagnostics, PolicyHook fail-closed policy behavior, on_handoff, LightSwarm runtime-context propagation, and complete Python 3.10/3.11/3.12 CI coverage.
  • v0.9.5: Added explicit memory promotion boundaries for internal reflection, delegation, self-learning, tool, trace, swarm, and shared-memory evidence; added non-injectable MemoryCandidate records, approve/reject/ rewrite/keep MemoryPromotionDecision handling, before_memory_promote and after_memory_promote hooks, promotion trace events, fail-closed promotion policy behavior, and optional OSS/NOS boto3 dependencies.
  • v0.9.6: Added production trace summaries and exporters, deterministic evaluation, tool/handoff human review, durable LightFlow approvals, review batches, human feedback, and shared Graph Memory fail-closed write admission and audit controls.
  • v0.9.7: Added the dependency-free Connector manifest and offline validation contract, two credential-free examples, expanded Python executor adversarial checks, an opt-in real Mem0 Graph security matrix, and the first public API compatibility inventory for the v1.0 stabilization line.
  • v0.10.0: Released the unified event-sourced Agent Runtime with durable Sessions, native async entry points, Capability Registry and Policy, Inbox/Goals/Budgets, compaction and recovery, Jobs/subagents, standardized Skills/MCP adapters, SQLite FTS5 retrieval, and compatibility adapters for the v0.9.x APIs.
  • v0.10.1: Removed arbitrary Python execution tools from the default Agent registration path, added the bounded safe_expression tool, and required an explicit SandboxProvider for model-triggered use of the opt-in compatibility executors.
  • v0.10.2: Hardened LightFlow with execution-scoped cancellation, normalized Agent exceptions, safe soft-timeout behavior, explicit overlap opt-in, executor cleanup, idempotent replay, and cancellation/idempotency propagation through Flow, Job, and child-Agent boundaries.

In Development

  • v0.11.0: Dynamic DAG Multi-Agent and Unified Security Context. This is the next development target after the v0.10.2 runtime-hardening release.

Next Feature Release

  • v0.11.0 (planned): Dynamic DAG Multi-Agent and Unified Security Context. Add an opt-in LightDAG layer for persistent task graphs, runtime decomposition, bounded concurrent workers, verified artifacts, and restart recovery while retaining the existing v0.11.0 security requirements. The implementation guide is LightDAG v0.11.0 development plan (Chinese). This plan does not change package versions or mark unreleased work complete.

Completed Milestone Details

These items came from the earlier roadmap 2.md draft and are now treated as shipped capabilities or established direction:

  • Stability and developer experience: preserve string-return compatibility while making structured RunResult available for callers that need trace IDs, errors, and structured run metadata. The legacy roadmap also called out content, reasoning_content, tool_calls, usage, trace_id, and error as the key result fields, plus catchable LightAgentError behavior, tool argument validation, example cleanup, stale import fixes, and focused unit tests for tool registry, runtime tools, stream/non-stream execution, error handling, and memory adapter behavior.
  • Trace and observability: keep human-readable debug logs separate from machine-readable trace events so production debugging can rely on structured data. The legacy roadmap also listed run_start, model_request, model_response, tool_call, tool_result, handoff, memory_read, memory_write, and run_end as the desired event vocabulary, with JSON export and Langfuse integration built on top of trace events.
  • Guardrails and safe tool execution: constrain input, tool calls, and final output through explicit policy while keeping default behavior lightweight. The legacy roadmap specifically called for prompt-injection checks, permission checks, high-risk tool-call policies, approval requirements for file/network/database/payment/external-action tools, output schema/PII checks, and memory guardrails for namespace, provenance, trust, and retrieval filtering.
  • LightFlow workflow orchestration: support deterministic workflow steps without turning LightAgent into a heavy orchestration framework. The merged legacy plan included explicit step input/output passing, per-step tools, model, memory, retry behavior, flow trace export, and later manual approval nodes.
  • Human-in-the-loop and recoverability: keep human approval, durable execution, run stores, idempotency markers, and resume semantics as planned follow-on work rather than core requirements for early 0.8.x releases.

The shipped LightFlow API should remain simple:

flow = LightFlow()

flow.step("research", agent=research_agent)
flow.step("analyze", agent=analysis_agent, depends_on=["research"])
flow.step("write", agent=writer_agent, depends_on=["analyze"])

result = flow.run("Analyze this company")

Open Pull Requests

  • Live pull-request state changes faster than this roadmap and should be read from GitHub. Documentation-only pull requests do not change the runtime version plan or release gates recorded here.

Active Issues

Immediate security-governance work:

  • #100 Python Executor sandbox escape disclosure: v0.10.1 removed the unsafe default registration path and introduced the bounded safe_expression replacement. Keep the public tracker open until the private Security Advisory confirms the affected configuration/version range and reporter attribution. The compatibility executor remains a controlled subprocess, not a security sandbox.

P1 security validation work:

  • #39 Shared graph memory security disclosure: the framework-level policy, admission, promotion, retrieval-filtering, audit, and fake-backend controls are shipped. Keep the issue open until the opt-in matrix is run against the exact isolated Mem0 Graph version and production-like storage configuration, then complete private advisory/CVE scoping from that evidence.

P2 issues:

  • #102 Optional MemCode memory integration: accept a focused, provider-owned adapter only if it remains outside core dependencies, fails closed on missing identity/scope, preserves MemoryPolicy metadata, supports retention and deletion, and includes credential-free fake-client tests.

Resolved or ready to close:

  • #1 Enhanced memory management for multi-agent systems: closed as completed after the shared-memory, policy, promotion, and adapter hardening work shipped.
  • #5 Custom plugin/integration development: v0.9.7 delivered the optional, dependency-free Connector manifest, offline validator, examples, and contributor documentation without adding a marketplace runtime.
  • #33 Optional ClawMem memory backend: #74 delivered the optional dependency-free adapter example, documentation, and fake-client tests.

Not planned for the core repository:

  • #26 External API tool bundle: closed as not planned; accept only focused, provider-owned examples outside required core dependencies.
  • #50 Nautilus A2A registry/discovery proposal: closed as not planned; keep vendor registration, wallets, and token economics in an external connector.
  • Broad marketplace, hosted review UI, hosted observability dashboard, or external API bundle in the default package.

Near-Term Version Plan

This section records the planned direction for the next several LightAgent versions after v0.9.7. Exact scope can still change as issues, pull requests, and user feedback evolve, but the intended product direction is:

event-sourced runtime + composable capability providers + unified policy + long-task control + recoverable context + stable APIs.

v0.8.3 Goals: LightFlow Execution Controls

Goal: make LightFlow easier to operate and debug in real multi-step workflows. These goals are completed as part of the v0.9.0 development line.

Completed in v0.9.0:

  • Clear step status tracking: pending, running, success, failed, skipped, and waiting_approval.
  • DAG validation for unknown dependencies, circular dependencies, and isolated step warnings.
  • Step-level timeout, cancellation, fallback-agent, and approval controls.
  • Flow trace output with step input summaries, output summaries, retry counts, error reasons, timing metadata, and fallback usage.
  • Focused tests for enhanced workflow controls.

Expected outcome:

Developers should be able to build and troubleshoot predictable LightFlow pipelines without relying on prompt-only control or external workflow engines.

v0.8.4 Goals: Memory And Guardrail Hardening

Goal: strengthen memory admission, memory retrieval safety, and guardrail templates for production usage. These goals are completed as part of the v0.9.0 development line.

Completed in v0.9.0:

  • Extend MemoryPolicy with expiration-aware retrieval through enforce_expires_at.
  • Improve memory write admission with min_write_length and reject_write_patterns.
  • Keep source, scope, agent, trust-level, and confidence filtering from the earlier memory-safety line.
  • Add reusable guardrail templates for privacy filtering, high-risk tool confirmation, sensitive parameter validation, and output redaction.
  • Clarify recommended boundaries between trace events, user memory, self-reflection memory, and LightSwarm delegation state.
  • Add more tests around memory provenance filtering, expiration filtering, blocked memory writes, and guardrail templates.

Expected outcome:

LightAgent should become safer for shared memory, customer service, internal knowledge assistant, financial analysis, and other high-impact agent use cases.

v0.9.0: Persistent LightFlow, Safety, And Shared Memory

Goal: extend LightFlow from an in-memory workflow runner into a lightweight checkpointed workflow system, while also shipping the memory and safety hardening required for long-running multi-agent workflows.

Completed work:

  • Add LightFlow step status tracking with pending, running, success, failed, skipped, and waiting_approval.
  • Add workflow validation for unknown dependencies, circular dependencies, and isolated step warnings.
  • Add step-level timeout, cancellation, fallback-agent, and approval controls.
  • Add JSON checkpoint storage through JsonLightFlowStore.
  • Add resume(run_id), rerun_step(run_id, step_name), get_run(run_id), and list_runs() workflow record APIs.
  • Persist intermediate step results and status for front-end execution views.
  • Add an in-memory SharedMemoryPool that satisfies MemoryProtocol.
  • Use append-first records with memory_id, created_at, user_id, and provenance metadata.
  • Keep user memory and agent reflection memory in separate scoped ids when used with LightAgent.
  • Allow direct inspection through list_records() and test cleanup through clear().
  • Pass MemoryScope-compatible metadata to memory backends that support a metadata keyword while preserving compatibility with two-argument legacy backends.
  • Add memory expiration filtering and basic low-quality write blocking through MemoryPolicy.
  • Add reusable guardrail templates for privacy filtering, sensitive tool confirmation, high-risk parameter validation, and output redaction.
  • Add tests for workflow controls, checkpoint/resume/rerun, scoped retrieval, append-first behavior, provenance filtering, guardrail templates, and LightAgent integration.

Deferred work:

  • SQLite or other database-backed run stores.
  • Distributed workers, locks, and stronger idempotency guarantees.
  • Advanced conflict-resolution policies beyond append-first storage.

Expected outcome:

Users can experiment with safer shared memory in LightAgent, LightSwarm, or LightFlow prototypes while preserving explicit provenance boundaries and a lightweight core.

v0.9.1: Runtime Hooks And Middleware

Status: first implementation slice completed.

Goal: add a small, ordered hook layer that unifies today's specialized extension points without turning LightAgent into a heavy plugin framework.

Why now:

  • v0.9.0 already has guardrails, trace events, memory write admission, LightFlow approval handlers, checkpoint/resume, and shared-memory prototypes.
  • New production needs such as cost control, model routing, prompt enrichment, tool auditing, PII redaction, evaluation, and approval policies should not require new one-off constructor parameters each time.
  • Hook support gives LightAgent a stable extension spine while preserving the existing lightweight, inspectable core.

Implemented in the first slice:

  • Added HookContext, HookDecision, and HookManager.
  • Added ordered sync hooks with isolated hook failures.
  • Added LightAgent(..., hooks=[...]) for before_run, before_model_request, after_model_response, before_tool_call, after_tool_result, before_memory_write, and after_memory_write.
  • Added LightFlow(hooks=[...]) for before_flow_step, after_flow_step, on_approval_required, on_resume, and on_rerun.
  • Added trace events for hook replacement, blocking, metadata, and hook failures through hook_decision and hook_block.
  • Added parent_trace_id and run_group_id support to agent traces, flow traces, LightFlow step calls, and memory write metadata.
  • Added after_run, on_error, before_memory_retrieve, and after_memory_retrieve to close the core agent and memory-read lifecycle.
  • Added async-compatible hook execution and production recipes for redaction, budgets, routing, tool policy, memory filtering, export, and evaluation sampling.
  • Kept existing agent.run("hello") and agent.run(query, stream=True, user_id=user_id) behavior compatible.

Remaining work after v0.9.3:

  • Add explicit fail-closed behavior for security policy hooks without changing the default failure isolation of observability hooks.
  • Add handoff hook support around the stabilized LightSwarm delegation path.
  • Continue hardening guardrail and memory policy adapter traces while preserving the current public APIs.
  • Expand production recipes as new integration targets appear.
  • Add pre-registration tool schema diagnostics so malformed tools can be found without changing runtime registration behavior.

v0.9.3: Runtime Hook Hardening And Stream Safety

Status: completed in v0.9.3.

Goal: stabilize the runtime hook lifecycle and stream safety behavior before adding larger workflow or observability features.

Completed work:

  • Close streaming tool-loop limit failures through _finish_run(...) so on_error, after_run, and run_end stay consistent.
  • Add max_tool_iterations as an explicit stream tool-call loop limit while keeping the default behavior compatible with max_retry.
  • Add focused regression tests for stream tool-loop limits, hook lifecycle closure, and trace behavior on failure.
  • Keep async hook support as completed v0.9.2 behavior and continue expanding sync/async hook coverage through tests.
  • Document how production applications can monitor stream tool-loop errors with on_error hooks.

Draft usage model:

from LightAgent import LightAgent, HookDecision


def redact_before_model(ctx):
    if ctx.phase == "before_model_request":
        messages = ctx.payload["messages"]
        redacted_messages = redact_private_data(messages)
        return HookDecision.replace(payload={"messages": redacted_messages})

    return HookDecision.continue_()


agent = LightAgent(
    name="assistant",
    role="Answer safely.",
    hooks=[redact_before_model],
)

Tool policy example:

def block_sensitive_tool(ctx):
    if ctx.phase == "before_tool_call":
        tool_name = ctx.payload["tool_name"]
        if tool_name in {"transfer_money", "delete_file"}:
            return HookDecision.block(reason="Sensitive tool requires approval")

    return HookDecision.continue_()

Supported hook points:

Area Hook point Typical usage
Run lifecycle before_run Input cleanup, permission checks, tenant context injection
Run lifecycle after_run Audit logging, evaluation sampling, result persistence
Model call before_model_request Prompt rewriting, PII redaction, model routing, budget checks
Model call after_model_response Output inspection, schema repair, quality scoring
Tool call before_tool_call Tool permission checks, argument validation, approval gating
Tool call after_tool_result Result filtering, error classification, audit logging
Memory read before_memory_retrieve Scope, tenant, user, agent, or trust-level constraints
Memory read after_memory_retrieve Expiration filtering, confidence filtering, re-ranking
Memory write before_memory_write Poisoning checks, deduplication, write-quality scoring
Memory write after_memory_write Audit recording, synchronization to external memory stores
Error handling on_error Fallback, retry classification, alerting
Multi-agent on_handoff Handoff audit, target-agent policy, delegation limits
LightFlow before_flow_step Step input validation, budget checks, cancellation policy
LightFlow after_flow_step Step output validation, trace enrichment, checkpoint metadata
LightFlow on_approval_required Integration with human approval systems
LightFlow on_resume State verification and external context restoration
LightFlow on_rerun Cleanup, historical result reuse, rerun policy checks

Hook decisions:

Decision Semantics
continue Continue without changing the current operation
replace Replace the current payload, such as messages, tool arguments, or memory content
block Stop the current operation with a structured reason
retry Request a retry for the current model, tool, or flow step
fallback Route to a fallback model, agent, tool, or flow branch
metadata Attach trace, audit, evaluation, or policy metadata

Expected outcome:

Developers should be able to extend LightAgent execution in production without forking the runtime or adding new framework-level parameters for every policy, observability, evaluation, routing, or enterprise integration requirement.

v0.9.4: Tool Contracts And Policy Safety

Status: completed in v0.9.4 and released on 2026-07-17.

Goal: make tool schemas inspectable before runtime and let security-sensitive hooks fail closed explicitly, while keeping existing hooks and tool registration behavior compatible.

Completed work:

  • Added ToolRegistry.validate_tool_info(tool_info) and registry-level validate_tools() diagnostics for names, descriptions, parameter lists, duplicate parameters, canonical types, and required flags.
  • Added LightAgent.validate_tools() as a convenience API.
  • Kept schema validation opt-in and read-only; invalid legacy schemas are not rejected by default.
  • Added PolicyHook with phase scoping, explicit failure mode, and optional sync/async timeout handling.
  • Kept plain hook failures isolated while allowing explicitly wrapped policy hooks to block on exceptions or timeouts.
  • Added on_handoff before LightSwarm delegation with block and metadata support, structured handoff trace events, parent trace propagation, and consistent source run_end closure.
  • Added focused tests with no model, network, MCP server, or external policy dependency.
  • Expanded GitHub CI to run the complete tracked test suite on Python 3.10, 3.11, and 3.12.
  • Preserved LightSwarm user_id, metadata, tracing options, result format, retry limits, and tool-iteration limits across entry runs and delegated handoffs.

Compatibility requirements:

  • Existing callable hooks continue after exceptions by default.
  • Existing register_tool() overwrite behavior remains unchanged.
  • Existing agent.run() and streaming return types remain unchanged.
  • No CCS or other policy engine is added to the core dependency set.

Expected outcome:

Applications can detect bad tool contracts before model execution and can mark specific authorization hooks as fail closed without making audit, metrics, or other observability hooks a new source of downtime.

v0.9.5: Memory Promotion And Shared Memory Safety

Status: the framework-level memory-promotion boundary was implemented in v0.9.5. Backend-level validation for #39 remains open.

Security scope: v0.9.5 is the first mitigation release for the #39 shared graph memory risk and completes the #82 explicit memory promotion workflow. It is not yet evidence that every shared Graph Memory backend is fully remediated.

Goal: make reflection, self-learning, delegation summaries, and shared-memory evidence safe by default before they can affect future user-facing prompts, and add the first human-review slice around memory promotion only.

Completed work:

  • Add an explicit memory promotion workflow for internal reflection and delegation summaries.
  • Treat reflection and delegation outputs as non-injectable memory candidates by default.
  • Add a promotion decision model that can approve, reject, rewrite, or keep a candidate non-injectable.
  • Add lifecycle hooks such as before_memory_promote and after_memory_promote, or an equivalent promotion callback API, for policy and human review.
  • Add a lightweight memory-candidate shape that carries run_id, trace_id, candidate ID, memory scope, source agent, trust level, confidence, reviewer metadata, and rejection or rewrite reason.
  • Support optional policy review for memory promotion with approve, reject, rewrite, and keep-non-injectable outcomes.
  • Keep memory-review hooks compatible with sync and async hook execution, including fail-closed handling for security-sensitive promotion policies.
  • Preserve provenance through source, scope, trust_level, confidence, agent_name, trace_id, parent_trace_id, run_id, and derived-memory lineage.
  • Record promotion candidates, decisions, rewrites, and blocks in trace or audit output without exposing raw sensitive memory text by default.
  • Record memory-review events such as memory_promotion_required, memory_promotion_approved, memory_promotion_rejected, memory_promotion_rewritten, and memory_promotion_blocked as the first Human-in-the-loop and Human-on-the-loop audit vocabulary.
  • Add fail-closed defaults for unattributed, unreviewed, cross-user, or cross-scope internal memory before prompt injection.
  • Add tests proving reflection, delegation, and shared-memory candidates cannot become prompt-injectable without explicit promotion.
  • Treat #39 as an ongoing backend-level security validation item. v0.9.5 includes deterministic framework tests for cross-user filtering and unreviewed internal-memory promotion paths, but does not yet prove containment against a realistic shared Graph Memory mutation pipeline.
  • Document safe patterns for SharedMemoryPool, mem0-style graph memory, vector memory adapters, and optional external memory backends such as ClawMem.
  • Document how external approval queues or review UIs can integrate with memory promotion through hooks without becoming core dependencies.

Delivered in v0.9.6:

  • Broader human-review surfaces for high-risk tools, handoffs, and LightFlow steps.

Still deferred:

  • Durable external review queues and admin UI examples.

Expected outcome:

LightAgent should give applications a clear and auditable path from internal agent evidence to durable prompt context, reducing memory poisoning and cross-user contamination risks while keeping existing memory backends compatible. v0.9.5 introduces human review as a narrow memory-promotion control, not as a general tool or workflow approval system.

v0.9.6: Observability, Evaluation, And Human Review

Status: completed in v0.9.6 and released on 2026-07-30.

Goal: improve production debugging, measurement, and human control over high-risk actions after the memory-promotion boundary and memory-scoped review path are explicit.

Completed work:

  • Added TraceSummary, normalized usage and cost estimates, model/tool latency, retry and error categories, review counters, generic exporters, and a JSONL audit exporter.
  • Added LightEvaluator and EvaluationCase for output, tool, policy-event, recovery, latency, usage, cost, and custom domain checks.
  • Added HumanApprovalHook, ApprovalRequest, ApprovalDecision, InMemoryReviewStore, and JsonReviewStore without adding a queue, UI, or database dependency.
  • Added fail-closed approval, rejection, argument editing, reviewer timeout, exact-context approval reuse, multi-action store batches, and trace feedback.
  • Added durable LightFlow request IDs and decisions with flow.approve(...); flow.resume(...), including approve, reject, edit, and respond behavior.
  • Extended structured traces with approval and feedback events while preserving existing agent.run() defaults and result formats.
  • Documented evaluation, external trace export, tool/handoff review, durable LightFlow approval, batches, and feedback integration.

Human-control expansion checklist completed in v0.9.6:

  • Formalize LightFlow requires_approval, approval_handler, and waiting_approval as the first Human-in-the-loop checkpoint model for deterministic workflows.
  • Use on_approval_required to notify external approval systems when a LightFlow step cannot continue without review.
  • Add a small approval request/result shape that can carry run_id, trace_id, action name, tool name, argument summary, source agent, target agent, allowed decisions, reviewer metadata, and rejection reason.
  • Support approve, reject, edit, and respond decision types for reviewed actions, while preserving simpler approve/reject behavior for existing LightFlow approvals.
  • Use PolicyHook on before_tool_call for fail-closed checks before sensitive tools such as file deletion, payments, database writes, shell execution, external API mutation, or customer-impacting actions.
  • Use PolicyHook on on_handoff to review or block delegation to another agent before LightSwarm transfers control.
  • Use tool schema diagnostics so reviewers and policies can inspect stable tool names, descriptions, required arguments, and duplicate or malformed parameters before approval.
  • Record hook_decision, hook_block, handoff, guardrail_block, approval, rejection, edit, feedback, and run_end events as the audit substrate for Human-on-the-loop monitoring.
  • Keep first-class human feedback queues, annotation workflows, online/offline evaluation dashboards, and web approval UIs optional rather than core dependencies.

Expected outcome:

LightAgent should support production environments where teams need to measure agent quality, inspect failures, review memory-promotion decisions, and keep humans in control of high-impact external side effects.

v0.9.7: Security Validation, Connector Contract, And Release Hardening

Status: released on 2026-08-15.

Goal: close the remaining security and extensibility gaps before the v1.0 API freeze. v0.9.7 should be a bridge release: small enough to ship quickly, but strong enough to reduce release risk around Python execution, shared memory, and third-party integrations.

Primary themes:

  • Security validation first: finish the #39 backend-level validation track before declaring shared Graph Memory risks fully handled.
  • Safer execution tools: build on merged #85 and extend Python executor tests beyond direct imports into attribute access, getattr, subscripted lookups, dynamic dispatch, import aliases, and builtins escape patterns.
  • Lightweight connector contract: address #5 with a small Python-native contract for packaging Tools, Skills, MCP server settings, Hooks, memory adapters, optional dependencies, and documentation.
  • v1.0 readiness: tighten public API inventory, compatibility promises, examples, packaging, and release notes before the stable line.

Implemented work:

  • Add a docs/security_shared_graph_memory_validation.md guide that separates framework-level mitigations from backend-specific Mem0 Graph validation.
  • Add an opt-in Graph Memory regression matrix for the exact Mem0 Graph version and storage settings used by maintainers or downstream deployments.
  • Add adversarial memory tests for cross-user poisoning, low-trust relation mutation, trusted-fact overwrite, entity-neighborhood merge, and retrieval audit counts.
  • Extended merged #85 with a table-driven _safe_import_check regression suite for direct calls, attribute-style calls, dynamic dispatch helpers, import aliases, __dict__/subscript access, and safe false-positive cases.
  • Document Python executor limitations clearly: AST filtering is defense in depth, not a complete sandbox; high-risk deployments should wrap execute_python_code with PolicyHook, Human Review, container isolation, timeout limits, network restrictions, and dependency-install controls.
  • Introduce a minimal connector manifest shape, such as a dataclass or plain dictionary, with fields for name, version, tools, skills, mcp_servers, hooks, memory_adapters, extras, and docs.
  • Add connector validation utilities that inspect tool schemas, optional dependency declarations, unsafe import hints, duplicate tool names, and missing documentation without loading network services.
  • Provide two dependency-free connector examples:
    • a local research connector that bundles a search-style tool and a Skill;
    • an enterprise API connector skeleton that shows auth/config placeholders without shipping secrets or provider SDKs.
  • Add a contributor guide for "build a connector in 10 minutes" using existing Tools, Skills, MCP, Hooks, and MemoryProtocol primitives.
  • Prepare v1.0 compatibility docs: public API inventory, deprecation policy, supported Python versions, dependency extras, and example coverage matrix.

Release gates:

  • #39 has either a private-security follow-up path or a documented public validation status that avoids overstating remediation.
  • #85 or equivalent Python executor hardening tests pass locally and in CI.
  • Connector contract remains optional and dependency-free in the core package.
  • Existing LightAgent, LightSwarm, LightFlow, tracing, evaluation, review, memory, and streaming compatibility tests remain green.
  • Docs clearly distinguish built-in primitives from optional integration examples.

Release validation: 193 passed, 1 opt-in Mem0 Graph test skipped, package compilation and wheel build passed, git diff --check passed, and GitHub CI passed on Python 3.10, 3.11, 3.12, and 3.13.

Expected outcome:

LightAgent enters the v0.10 runtime-evolution phase with fewer loose security threads, a practical answer to custom integrations, and clearer boundaries around what the lightweight core will and will not own.

Post-v0.9.7 Runtime Design Guardrails

The next development line should strengthen the runtime without turning the core package into a hosted platform or a mandatory collection of heavyweight integrations.

  • Preserve agent.run("hello"), stream=True, structured results, existing Tools, Hooks, Memory backends, LightSwarm, and the LightFlow chain API.
  • Make every model-visible message, tool result, memory item, approval result, steering message, and compaction summary reconstructable from durable Session events.
  • Separate capability execution from policy decisions: a Provider implements an operation, while Policy, Sandbox, Guardrails, and Approval decide whether that operation may run.
  • Require child Agents, Skills, and Workflow steps to inherit or reduce parent permissions; task code must never expand its own capability set.
  • Make the runtime async-first while retaining synchronous compatibility wrappers.
  • Keep Browser, Docker, LSP, vector databases, WebUI frameworks, and hosted services as optional Providers or upper-layer product capabilities.
  • Distinguish model errors, tool failures, policy denials, approval waits, budget exhaustion, cancellation, and context overflow with explicit states and error codes.

v0.10.0: Unified Event-Sourced Agent Runtime

Status: released as v0.10.0; post-release security and provider validation continues under the v0.10.1 and later stabilization plans.

Goal: deliver one coherent runtime release that combines the previously planned v0.10.0-v0.15.0 capabilities without breaking v0.9.x applications. This goal is complete. The remaining work is tracked as post-v0.10 security and stabilization releases rather than as an unfinished v0.10.0 milestone.

Implementation delivered in the v0.10.0 development PR:

  • Versioned Session events, in-memory/JSONL/SQLite stores, replay, pagination, checkpoints, fork lineage, migration hooks, context/trace projection, and explicit incomplete-Turn detection.
  • Compatible arun()/astream() entry points and durable model/tool/runtime lifecycle recording without changing default run() return behavior.
  • Scoped Capability Registry, Provider lifecycle, deterministic conflict diagnostics, narrowing-only permissions, unified Policy decisions, audit configuration digests, and adapters for Tools, Memory, Skills, MCP, and LightFlow.
  • Durable Inbox, Goals, Budgets, progress detection, Jobs, bounded subagents, context budgets, deterministic/summary compaction, oversized-tool spill references, Session control events, and restart restoration.
  • Deterministic Skill precedence, conflict reporting, nested AGENTS.md discovery, MCP Streamable HTTP/reconnect/refresh/namespaces/credential headers, SQLite FTS5 RAG, and citation-based cross-Session search.
  • Focused v0.10 protocol, persistence, corruption, policy, runtime, async, compatibility, and retrieval tests plus complete legacy regression testing.

Post-release validation and follow-up work:

  • Python 3.10-3.13 GitHub Actions, package build/install, and real provider smoke tests.
  • Fault injection against real MCP Streamable HTTP, process interruption, concurrent persistent writes, and context-overflow provider responses.
  • Contract tests for optional Browser, Terminal, Shell, LSP, vector, sandbox, and hosted-service Providers supplied outside the lightweight core.

Milestone 1: Event-Sourced Sessions And Native Async

  • Add versioned Session, SessionEvent, and SessionStore contracts.
  • Define Session, Turn, Step, Message, Model, Tool, Approval, Error, and lifecycle events with schema validation and migration hooks.
  • Provide dependency-free in-memory and JSONL stores plus an optional SQLite store based on the Python standard library.
  • Add Session export, pagination, replay, recovery, and incomplete-Turn detection.
  • Derive model context and the current TraceRecorder view from the same event history instead of maintaining unrelated sources of truth.
  • Add native agent.arun() and retain run() as a compatibility wrapper.
  • Record balanced model request/response and tool request/result pairs with explicit interrupted and failed terminal states.

Milestone 2: Capability Registry And Unified Policy

  • Add CapabilityProvider and CapabilityRegistry protocols with mount, start, health, reload, stop, and unmount lifecycle methods.
  • Support Runtime, Session, and Agent scopes with deterministic resolution and conflict diagnostics.
  • Define protocols for Model, Tool, FileSystem, Shell, Terminal, Browser, Web, LSP, Memory, RAG, Subagent, Workflow, Interaction, Sandbox, Credential, Policy, and Telemetry Providers.
  • Adapt existing Tools, MCP, Memory, Connector, LightFlow, Hooks, Guardrails, and approval APIs instead of introducing a parallel plugin runtime.
  • Add capability metadata for read/write/network/execute behavior, risk, timeout, output limits, cancellation, persistence, and optional dependencies.
  • Route sensitive operations through one Policy decision path and record the Provider name, version, and configuration digest in audit events.

Milestone 3: Agent Inbox, Goals, And Budgets

  • Add a durable Agent Inbox for followup, steering, context, and approval messages.
  • Queue and consume messages in order, injecting steering only at safe Step boundaries.
  • Add durable Goals with acceptance criteria, subgoals, completion evidence, blockers, and status transitions.
  • Add model-call, tool-call, token, time, and estimated-cost budgets.
  • Support pause, resume, cancel, and continue through Session events.
  • Add no-progress detection, repeated-tool detection, bounded retry, and message idempotency keys.

Milestone 4: Context Compaction, Checkpoints, And Fork

  • Add model-aware token accounting and configurable context budgets.
  • Implement two-stage compaction: deterministic trimming first, optional LLM summarization second.
  • Spill oversized tool results outside the prompt while retaining event-backed references and integrity metadata.
  • Persist compaction summaries and covered event ranges as versioned Session events.
  • Add Session checkpoints, restore validation, and Fork from a selected event boundary.
  • Support bounded recovery from context-overflow errors and an optional dedicated summarization model.

Milestone 5: Multi-Agent, Jobs, And Workflow Unification

  • Unify LightSwarm, handoff, and subagent lifecycle events while preserving existing LightSwarm behavior.
  • Support one-shot, persistent, and Session-Fork subagents with depth, count, concurrency, and budget limits.
  • Add Agent-tree inspection, messaging, interruption, resume, and result collection.
  • Freeze auditable child-permission snapshots and prohibit capability escalation.
  • Add background Jobs with status, incremental output, cancellation, and Inbox completion notifications.
  • Evolve LightFlow into the common Workflow Provider for fixed DAGs, dynamic model-planned workflows, checkpoints, approvals, reruns, and parallel steps.
  • Scope clarification (2026-09-14): the dynamic graph and dependency-parallel portions above remain planned, not shipped v0.10.0 capabilities. They move to the opt-in v0.11.0 LightDAG layer; existing LightFlow execution semantics remain compatible.
  • Add optional persistent Terminal and LSP Providers without making them core dependencies.

Milestone 6: Memory, Skills, MCP, And Knowledge Standardization

  • Standardize Working, Session, Workspace, User, and Shared Memory scopes with owner, tenant, provenance, TTL, trust, sensitivity, and admission metadata.
  • Keep automatic Memory writes and promotion behind MemoryPolicy, Policy, and optional approval.
  • Support user, workspace, nested-directory, managed, and built-in Markdown Skills with deterministic precedence and conflict diagnostics.
  • Add compatible project instruction discovery such as AGENTS.md without runtime self-modification.
  • Add MCP Streamable HTTP, reconnect, tool-list refresh, namespace isolation, and external Credential Provider integration while retaining stdio/SSE configuration compatibility.
  • Define a Retrieval/RAG Provider and ship an optional SQLite FTS5 minimum implementation; keep embeddings, vector databases, reranking, and hybrid retrieval optional.
  • Add cross-Session text search with citations while keeping Session Search separate from knowledge-base retrieval.

v0.10.0 Compatibility Commitments

  • Preserve agent.run("hello"), stream=True, structured results, existing Tools, Hooks, Guardrails, Memory backends, LightSwarm, and LightFlow APIs.
  • Existing users can adopt Session, Registry, Inbox, Goal, compaction, subagent, and knowledge features incrementally; none becomes mandatory for a basic Agent.
  • Existing Trace, Tool, Memory, Hook, MCP, LightSwarm, and LightFlow data is exposed through compatibility adapters instead of forced migration.
  • Browser, Docker, LSP, vector databases, hosted services, and WebUI frameworks remain optional.

v0.10.0 Release Gates

  • Every model request can be reconstructed deterministically from persisted Session events, and model/tool/approval records remain balanced.
  • Process interruption, EventLog failure, context overflow, Provider failure, and incomplete Turns have explicit recoverable or terminal states.
  • Provider contract and cleanup tests prove that replacement and unload do not leak tools, listeners, processes, credentials, or stale registrations.
  • Write, network, execution, credential, and persistence operations cannot bypass Policy, approval, scope inheritance, or audit handling.
  • Restart preserves Inbox order, Goal state, pending approvals, budgets, checkpoints, and idempotency markers.
  • Compaction preserves unresolved Goals, approvals, decisions, file changes, tool lineage, and replay integrity.
  • Child Agent and Job failures cannot erase parent state; concurrent writes are denied or serialized unless explicitly allowed.
  • Workflow and Agentic Loop execution use the same Session, capability, Policy, approval, budget, and recovery contracts.
  • Memory, Skill, MCP, RAG, and Session Search retain source, owner, scope, and provenance metadata; MCP reconnect cannot duplicate tools.
  • The Runtime remains usable without vector, Browser, Docker, hosted service, or model-gateway dependencies.
  • The complete v0.9.7 compatibility suite passes on Python 3.10-3.13, together with replay, migration, corruption, fault-injection, long-task, concurrency, security, package-build, and import tests.

v0.10.1: Security Boundary And Runtime Hardening

Status: released on 2026-09-05 as the immediate security patch for the v0.10 runtime. It disabled automatic arbitrary-Python tool registration, added the bounded safe_expression path, and introduced fail-closed SandboxProvider gating. Broader unified security-context work continues in v0.11.0.

Goal: ensure that every capability call is checked by identity, capability, policy, approval, resource, environment, and credential boundaries. This release prioritizes the P0 Python Executor disclosure in #100 and must not be delayed by unrelated feature work.

Python Executor boundary

  • Stop auto-registering arbitrary Python, Python-file, and streaming execution tools by default.
  • Preserve the public imports for compatibility, but require explicit capability and policy opt-in for trusted-code execution.
  • Add a safe expression mode based on a strict AST allowlist for arithmetic, comparisons, literals, and bounded containers.
  • Reject imports, attributes, reflection, dynamic dispatch, file access, network access, process access, and dynamic dependency installation in safe expression mode.
  • Do not fall back to host execution when a SandboxProvider is unavailable.
  • Treat Docker, a rootless container, or another isolated execution provider as the boundary for arbitrary code. AST checks remain defense in depth only.
  • Keep requirements installation disabled by default and require explicit policy approval when enabled.
  • Resolve the #95 JSON parsing regression without swallowing unrelated cleanup exceptions.

Unified capability security gate

All Tool, Python, Shell, Terminal, MCP, Skill, Browser, Memory, subagent, and Job calls should follow the same conceptual path:

Identity -> CapabilityRegistry -> PolicyEngine -> ApprovalVerifier
         -> Provider -> Sandbox/Credential/Network gate -> execution

The model may propose a call, but must not be able to change permissions, approval state, sandbox policy, network policy, or credentials.

Approval and secret safety

  • Bind approvals to the canonical capability arguments, workspace, agent, session, policy version, risk level, expiry, and a one-time token.
  • Recompute and verify the approval binding immediately before execution.
  • Add SecretRef and resolve credentials only at the final Provider boundary.
  • Redact secrets from prompts, tool arguments, Sessions, traces, logs, SSE, Memory, RAG, child-agent context, and error messages.
  • Ensure child Agents do not inherit raw credentials by default.

Persistence and resource controls

  • Add atomic Session append with expected sequence checking.
  • Add atomic Inbox claims, leases, idempotency keys, and explicit completion states.
  • Enforce model-call, tool-call, token, time, output-size, child-agent, browser, container, and network-request budgets.
  • Distinguish policy denial, approval wait, provider failure, cancellation, budget exhaustion, and context overflow with structured states and codes.

v0.10.1 security release gates

  • Isolated reproduction and scope assessment for #100 through the Security Advisory process; do not publish affected versions until verified.
  • Safe-expression, default-registration, policy-bypass, approval-substitution, secret-redaction, and sandbox-unavailable tests.
  • Atomic Session/Inbox, idempotency, resource-limit, and restart tests.
  • Python 3.10, 3.11, 3.12, and 3.13 CI, package build, install, and import checks.
  • Complete legacy compatibility suite, with agent.run("hello") and stream=True behavior preserved where the security boundary permits it.

v0.10.2: LightFlow Runtime Hardening

Status: released on 2026-09-14 through PR #103.

Goal: stabilize workflow failure, cancellation, timeout, and recovery behavior after the P0 security patch is released.

  • Normalize raised Agent exceptions so retry, fallback, and failed-step paths behave consistently with returned RunResult errors.
  • Replace the shared sticky cancellation flag with an execution-scoped token or generation captured by run(), resume(), and rerun_step().
  • Define timeout as a soft timeout unless a terminable SandboxProvider is used; avoid silently creating duplicate side effects during retry or fallback.
  • Ensure executor cleanup on success, timeout, and raised exceptions.
  • Add idempotency and cancellation propagation for Flow steps, Jobs, and child Agents.
  • Rebase and combine the relevant work from #97, #98, and #99 only after the interaction tests and full CI suite pass.

Released in v0.10.2:

  • Added execution-scoped CancellationToken handling for run(), resume(), and rerun_step(), including targeted run_id cancellation and non-sticky reuse of a LightFlow instance.
  • Normalized raised Agent and fallback exceptions into retryable failed-step results without persisting raw exception details.
  • Fixed executor cleanup so soft timeouts return promptly on success, timeout, and raised-exception paths.
  • Made timeout retry/fallback overlap explicit through allow_timeout_overlap=True; the default fails without launching duplicate in-flight work.
  • Added local run-ID idempotent replay, stable step idempotency keys, Job idempotency, and cooperative cancellation propagation to Jobs and subagents.
  • Combined the relevant behavior from #97, #98, and #99 with interaction and compatibility tests.

v0.11.0: Dynamic DAG Multi-Agent And Unified Security Context

Status: planned next feature release after v0.10.2.

Goal: add persistent, dynamically decomposed, verification-driven multi-agent execution and make security decisions explicit across runtime capabilities. The existing security work below remains required. Detailed contracts, implementation stages, and release gates are defined in the LightDAG development plan.

Dynamic DAG work:

  • Add opt-in LightDAG, a SQLite task graph store, transactional graph mutations, cycle detection, versioned task attempts, and durable DAG events.
  • Schedule independent tasks concurrently through isolated Worker factories; retain LightFlow's existing fixed-workflow behavior.
  • Distinguish decomposition acceptance, candidate submission, and verified completion; require parent integration verification after dependencies finish.
  • Add immutable artifact manifests, verification reports bound to input and content hashes, retrieval adapters, and bounded local task context.
  • Implement single-host scheduler and task leases, stale-attempt rejection, idempotent publication, budget reservations, and restart recovery.
  • Ship credential-free deterministic examples, compatibility coverage, and process-level fault tests. Cross-machine workers, WebUI, and domain toolchains remain optional or future work.

Unified security work:

  • Add SecurityContext carrying user, tenant, session, run, agent, parent agent, capability, resource, permissions, network, sandbox, approval, and deadline information.
  • Add CapabilityGate and route every sensitive Provider call through it.
  • Add versioned ApprovalToken, ProviderManifest, and event sensitivity metadata.
  • Add immutable child-agent permission snapshots with narrowing-only inheritance, independent sessions, workspaces, budgets, and credentials.
  • Add Job leases and cancellation tokens with parent-to-child propagation.

v0.12.0: Trusted Data And Supply Chain

Goal: prevent external content and untrusted extensions from changing runtime authority.

  • Wrap web, RAG, PDF, uploaded files, Memory, Skills, MCP results, and child reports as untrusted data rather than executable instructions.
  • Make Memory and RAG admission, provenance, trust, TTL, source hash, and citation tracking default behavior.
  • Prevent low-trust facts from replacing high-trust facts without explicit approval, and support rollback of unsafe writes.
  • Add Skill/MCP version locks, content digests, publisher metadata, capability declarations, signature verification, and upgrade re-trust.
  • Add MCP namespace isolation, network egress allowlists, and default-deny dynamic installation.

v0.13.0: Recovery And Adversarial Security

Goal: validate security and recovery behavior under interruption, concurrency, malicious content, and resource pressure.

  • Add Session hash chains and integrity verification.
  • Add atomic Inbox claim/release and durable Job recovery.
  • Add prompt-injection, malicious MCP/Skill, child-agent privilege, resource exhaustion, and concurrent-write test suites.
  • Verify that restart does not repeat side effects and that replay preserves security decisions, approvals, citations, and provenance.
  • Publish sanitized security evaluation results and operational configuration guidance.

v1.0.0: Stable Runtime And Ecosystem

Goal: freeze the runtime and security contracts only after v0.10.1-v0.13.0 have survived compatibility, fault, concurrency, and adversarial validation.

Planned work:

  • Freeze the public API, Provider protocols, Session event schemas, Policy decisions, and compatibility adapters.
  • Publish a versioned deprecation and migration policy with tooling for v0.9.x Session, Trace, Tool, Memory, Hook, LightSwarm, and LightFlow users.
  • Provide a Headless Runner, Python SDK, and optional JSON-RPC service surface.
  • Publish official Provider templates and contract-test kits.
  • Complete multilingual production documentation and the supported example matrix.
  • Add OpenTelemetry, Langfuse, and JSONL exporters through optional adapters.
  • Establish performance, recovery, tool-call, multi-agent, and workflow reliability benchmarks.
  • Automate signed package build, PyPI publishing, release notes, and rollback checks.

Release gates:

  • Public contracts have passed the complete v0.10.0 milestone suite and the v0.10.1-v0.13.0 security stabilization cycle.
  • Event schemas support forward migration and deterministic replay.
  • Long-task interruption recovery passes in deterministic test environments.
  • Multi-Agent, approval, compaction, MCP, and Provider lifecycle paths pass fault-injection tests.
  • Core installation does not require Browser, Docker, vector databases, model gateway SDKs, or Web frameworks.
  • The v0.9.x-to-v1.0 migration guide and compatibility suite are complete.

v1.1.0: Enterprise Integration

Goal: make LightAgent easier to embed into internal systems after the runtime contracts are stable.

Planned work:

  • Add multi-tenant policy templates and reference deployment profiles.
  • Provide tool-level permission, credential, and audit patterns.
  • Add optional Docker and service-wrapper deployment templates.
  • Improve model routing guidance for compatible endpoints, LiteLLM, local inference, and private gateways.
  • Add enterprise examples without placing business workflows or hosted user interfaces in the core package.

Unified v0.10.0 Quality Gates

Every internal v0.10.0 milestone must extend, not replace, the following validation layers. Passing an early milestone does not authorize releasing a partial v0.10.0 as the final version:

  1. Protocol and state-machine unit tests.
  2. Provider contract and resource-cleanup tests.
  3. Session replay, migration, projection, and corruption tests.
  4. Compatibility tests for all v0.9.7 public APIs.
  5. Security tests for Policy, Sandbox, Approval, Credential, and scope inheritance.
  6. Fault injection for model streams, tools, stores, MCP, Providers, Jobs, and subagents.
  7. Long-task tests covering budgets, compaction, checkpoint, resume, and idempotency.
  8. Python 3.10, 3.11, 3.12, and 3.13 CI plus package build and import checks.

Suggested release cadence:

Version Theme Suggested cycle
v0.10.0 Unified event-sourced Agent Runtime Released
v0.10.1 Security boundary and runtime hardening P0 patch release
v0.10.2 LightFlow runtime hardening After v0.10.1
v0.11.0 Dynamic DAG Multi-Agent and unified security context After v0.10.2; gated by the development plan
v0.12.0-v0.13.0 Trusted data, supply chain, and broader recovery hardening Milestone-driven
v1.0.0 API freeze and production hardening After security gates
v1.1.0 Optional enterprise integration Post-v1.0 feedback-driven

Reference Directions From Other Agent Frameworks

Current agent frameworks are converging around several production-oriented capabilities:

  • LangGraph / LangChain: durable execution, checkpointing, human-in-the-loop workflows, long-running stateful tasks, and middleware hooks around agent/model/tool execution.
  • CrewAI: combining autonomous agent collaboration with deterministic workflow orchestration through Crews and Flows.
  • OpenAI Agents SDK: handoffs, guardrails, tracing, lifecycle hooks, and production-oriented agent execution primitives.
  • Microsoft AutoGen: multi-agent conversations, collaboration protocols, and agent-to-agent coordination.
  • Microsoft Semantic Kernel: filter pipelines around prompt rendering, function invocation, auto function invocation, and policy interception.
  • Pydantic AI: typed tools, structured output, schema validation, and type-safe agent interfaces.
  • LlamaIndex: data-oriented agents, workflows, RAG, document pipelines, and knowledge retrieval.

Human Control Patterns From External Frameworks

External HITL/HOTL designs suggest a clear split between the lightweight runtime foundation that belongs in LightAgent core and the heavier product surfaces that should remain optional. These patterns informed the v0.9.5 memory-review slice and the v0.9.6 human-review implementation:

  • Pause and resume: OpenAI Agents SDK and LangGraph both model HITL as an interruption/pause point that returns pending actions and resumes from saved state after review. LightAgent keeps durable LightFlow approval checkpoints as the lightweight core version of this pattern.
  • Decision vocabulary: LangGraph exposes approve, reject, edit, and respond decision types. LightAgent v0.9.5 applies approve, reject, and rewrite to memory promotion first; v0.9.6 extends approve, reject, edit, and respond behavior to tools and workflow checkpoints.
  • Tool-level approval: OpenAI Agents SDK applies approvals to sensitive tool calls, nested agent tools, shell/apply-patch tools, and MCP tools. LightAgent maps this to before_tool_call, HumanApprovalHook, PolicyHook, Guardrails, and tool schema diagnostics rather than adding a separate heavy approval runtime.
  • Handoff review: OpenAI approval surfaces work across handoffs and nested agent-as-tool calls. LightAgent keeps on_handoff as the core LightSwarm review point.
  • Fail-closed policy: Semantic Kernel filters and OpenAI guardrail/tool approval patterns emphasize policy checks before execution. LightAgent keep plain hooks failure-isolated, but use PolicyHook for fail-closed security decisions.
  • Human-on-the-loop monitoring: LangSmith and Microsoft Responsible AI guidance emphasize trace review, feedback capture, annotation queues, telemetry, audit logs, and escalation paths. LightAgent v0.9.5 begins with memory-promotion review events; v0.9.6 adds broader monitoring on the same trace/audit substrate while keeping review queues, dashboards, and evaluators optional integrations.

LightAgent should borrow the strongest production ideas from these frameworks while preserving its own identity: small, direct, Python-native, Skills-first, and OpenAI-compatible.

Positioning

LightAgent should not become a second LangGraph, CrewAI, or LlamaIndex. Its strongest path is to remain:

  • lightweight;
  • explicit;
  • low-dependency;
  • Python-native;
  • OpenAI-compatible;
  • Skills-first;
  • easy to inspect;
  • easy to extend.

The highest-value work is improving reliability, observability, safety, tests, workflow composition, and memory boundaries while keeping the core simple.

v0.8.1: Memory, Trace, And Swarm Boundary Safety

Goal: prevent trace observability, persistent memory, and LightSwarm self-reflection from collapsing into one uncontrolled feedback loop.

This was the first partial response to issues #57, #39, and #1. The first framework-level #39 mitigation and the #82 promotion boundary shipped in v0.9.5 through explicit memory promotion.

Completed Work

  • Document the recommended separation between:
    • per-run trace events;
    • user conversation memory;
    • agent self-reflection memory;
    • LightSwarm delegation state.
  • Add MemoryScope as a metadata convention for memory writes:
    • source: user, agent, tool, trace, reflection, or swarm;
    • scope: user, agent, session, flow, swarm, or project;
    • agent_name;
    • trace_id;
    • optional parent_trace_id;
    • optional confidence / trust_level.
  • Extend MemoryPolicy and tests so retrieved memories can be filtered by source, scope, user, and agent provenance.
  • Add docs that explain the current trace model:
    • each agent.run() has its own trace_id;
    • nested reflection or delegated runs should be treated as sibling traces unless the caller wires parent_trace_id;
    • LightSwarm traces are not automatically folded into parent traces yet.
  • Add regression tests for memory provenance filtering and reflection-memory isolation.

Expected Outcome

Users should understand how to prevent self-reflection, trace summaries, and delegated agent outputs from being stored as ordinary user memory. LightAgent should provide a clear convention that future memory adapters can follow.

v0.8.2: Memory Admission And Mutation Controls

Goal: make memory writes safer before adding deeper shared-memory features.

Completed Work

  • Add optional memory write admission hooks through MemoryPolicy.
  • Support simple per-run write limits for memory mutations.
  • Add lightweight duplicate write blocking using scope-aware fingerprints.
  • Emit memory_write and memory_write_block trace events without raw memory text.
  • Document write-time controls for high-impact or shared memory backends.
  • Keep default behavior unchanged for simple single-agent usage.

Expected Outcome

LightAgent should have a minimal but practical first layer against memory poisoning, write amplification, and reflection cascades.

Detailed Backlog For Planned Releases

v0.9.0 Workstream: Persistent LightFlow, Safety, And Shared Memory

Goal: provide checkpointed workflow execution, reusable safety controls, and a lightweight shared-memory design without adding heavy storage dependencies.

Completed Work

  • Add explicit LightFlow step status, richer step traces, timeout, cancellation, fallback-agent, approval, checkpoint, resume, rerun, and run record APIs.
  • Add JSON-file workflow persistence through JsonLightFlowStore.
  • Persist intermediate step results so long-running workflows can resume after failure instead of restarting from the first step.
  • Add an in-memory SharedMemoryPool implementation.
  • Keep records append-first instead of overwrite-by-default.
  • Store memory_id, created_at, user_id, memory, and provenance metadata on each record.
  • Support scoped retrieval by user_id, agent_name, source, and scope.
  • Preserve compatibility with MemoryPolicy by returning retrieval records with user_id and metadata.
  • Update LightAgent to pass memory metadata to backends that support it while preserving the existing two-argument MemoryProtocol.
  • Add memory expiration filtering, minimum write length checks, and reject patterns for low-quality memory writes.
  • Add default guardrail templates for privacy filtering, sensitive tool confirmation, high-risk parameter validation, and output redaction.
  • Add tests for multi-agent read/write isolation and reflection-memory separation, persistent workflow records, resume, rerun, approval, fallback, memory admission, and guardrail templates.

Expected Outcome

LightAgent users should be able to experiment with shared memory in LightSwarm or LightFlow while preserving explicit boundaries and inspectable behavior.

v0.9.1 Workstream: Runtime Hooks And Middleware

Status: first implementation slice completed in v0.9.1. Run-end, error, and memory-read lifecycle hooks completed in v0.9.2. Remaining items should move into the next hook hardening release unless user feedback reprioritizes observability or persistence work.

Goal: introduce a minimal lifecycle hook system that lets applications observe, modify, block, retry, or route execution at well-defined points.

Completed First Slice

  • Add a HookContext data object that carries stable run metadata and the phase-specific payload.
  • Add a HookDecision return object with explicit control decisions rather than relying on exceptions or ad hoc booleans.
  • Implement a HookManager that runs hooks in deterministic order and isolates hook failures.
  • Cover run start, model request/response, tool call/result, memory write, and LightFlow step, approval, resume, and rerun phases.
  • Record hook activity through trace events so blocked operations and payload changes are auditable.
  • Add trace hierarchy fields through parent_trace_id and run_group_id.
  • Add run-end, error, memory-read, and async-compatible hook execution in the v0.9.2 line.

Completed Follow-up

  • Harden stream failure paths so hook lifecycles stay consistent when tool-call loops hit safety limits.
  • Add PolicyHook so security-sensitive hooks can fail closed while ordinary observability hooks remain failure-isolated.
  • Add on_handoff after the LightSwarm handoff contract stabilized.
  • Add production recipes for redaction, budgets, routing, tool policy, memory filtering, export, and evaluation sampling.
  • Add compatibility tests so agent.run(), streaming, structured results, guardrails, memory policy, LightSwarm, and LightFlow behavior remain compatible when no hooks are configured.

Remaining Work

  • Convert or adapt existing guardrails and memory write admission into the new lifecycle model where it simplifies implementation, without breaking current public APIs.
  • Reuse the hook layer for v0.9.5 memory promotion, especially policy review, human review, and trace/audit export.
  • Document common hook recipes:
    • PII redaction before model calls;
    • budget enforcement before model/tool execution;
    • tool allow/deny policy before execution;
    • OpenTelemetry or Langfuse export;
    • model routing and A/B experiments;
    • prompt enrichment from application context;
    • evaluation sampling after runs;
    • memory promotion approval and rejection.

Draft API Contract

  • hooks=[callable_or_hook_object] should be accepted by LightAgent and optionally by LightFlow.
  • A simple hook callable should receive one HookContext argument and return a HookDecision, HookResult, None, or a compatible dictionary.
  • None should mean continue, so simple observability hooks can avoid boilerplate return values.
  • Hook objects may expose named methods such as before_model_request(ctx) or after_tool_result(ctx) when that is clearer than branching on ctx.phase.
  • Hook ordering should be deterministic and documented. Later versions can add explicit priority, but the first version should preserve list order.
  • Hook failures should be recorded as trace events. The default behavior should fail closed only for policy hooks that explicitly request blocking semantics; observability hooks should not crash the agent by default.
  • Guardrails and MemoryPolicy.memory_write_admission should continue to work with their current public APIs while the implementation starts routing them through the same lifecycle concepts.

Expected Outcome

LightAgent should gain an extension mechanism that is powerful enough for production policy and observability work, but small enough to keep the framework direct, Python-native, and easy to inspect.

v0.9.5 Workstream: Memory Promotion And Shared Memory Safety

Status: completed as the v0.9.5 release line.

Goal: close the gap between internal agent evidence and future prompt context. Reflection, self-learning, delegation summaries, and shared-memory evidence should not become prompt-injectable memory unless an explicit policy or memory-scoped human review promotes them.

Completed Work

  • Add a memory-candidate representation for reflection and delegation outputs.
  • Mark internal candidates as non-injectable by default.
  • Add an explicit promotion API or lifecycle hook that can approve, reject, rewrite, or keep candidates non-injectable.
  • Add a memory-candidate and promotion-decision shape for optional policy or human approval of memory promotion.
  • Support sync and async memory-review hooks with fail-closed behavior for security-sensitive promotion decisions.
  • Preserve full provenance and lineage across promotion decisions.
  • Add trace/audit events for promotion candidates, approvals, rejections, rewrites, blocks, and final decisions.
  • Add fail-closed tests for unattributed, unreviewed, cross-user, cross-agent, and cross-scope memory candidates.
  • Make those tests the v0.9.5 framework-level release gate for #82 memory promotion safety and the first mitigation checkpoint for #39. Keep realistic shared Graph Memory backend tests as follow-up acceptance criteria.
  • Update memory security docs for SharedMemoryPool, mem0-style graph memory, vector memory adapters, and optional ClawMem-style adapters.
  • Document memory-review integration patterns for external approval queues, ticketing systems, or lightweight admin UIs without adding those systems as core dependencies.

Expected Outcome

LightAgent should reduce shared-memory poisoning risk and provide a clear, auditable path from internal reflection or delegation evidence to durable user memory. This release should also provide the first narrow Human-in-the-loop surface, limited to memory promotion decisions.

v0.9.6 Workstream: Observability, Evaluation, And Human Review

Status: completed in v0.9.6 and released on 2026-07-30.

Goal: support production teams that need measurement, review, and control over agent behavior after the memory-promotion boundary and memory-review slice are explicit.

Completed Work

  • Rich trace summaries, latency/usage/retry/error metadata, generic export, and local JSONL audit envelopes.
  • Dependency-free deterministic evaluation with custom checks and aggregate reports.
  • Fail-closed tool and handoff review through HumanApprovalHook.
  • Durable LightFlow approval checkpoints with approve, reject, edit, respond, and resume behavior.
  • Multi-action review-store batches and human feedback records.
  • Approval and feedback trace events for Human-on-the-loop monitoring.

Expected Outcome

LightAgent should support workflows where a model can plan and prepare actions, but humans retain control over important external side effects and memory promotion decisions.

v0.9.7 Workstream: Security Validation And Connector Contract

Status: released on 2026-08-15.

Goal: harden the remaining high-risk surfaces and define a minimal custom integration path before the v1.0 API freeze.

Implemented Work

  • Treat #39 shared Graph Memory validation as the top security workstream: keep public wording conservative, move reproduction/version scoping into an appropriate private advisory workflow, and add backend-specific opt-in tests.
  • Build on merged #85 with broader Python executor AST blocklist hardening.
  • Expand Python executor security regression tests for:
    • builtins.eval, builtins.exec, and builtins.compile;
    • getattr(obj, "eval"), getattr(obj, "system"), and similar helpers;
    • obj.__dict__["eval"](...) and other subscripted call patterns;
    • aliased imports and nested dangerous module access;
    • benign math/list/string code that should remain allowed.
  • Add docs that position execute_python_code as a controlled utility, not a complete sandbox. Recommend tool allowlists, PolicyHook, Human Review, container-level isolation, timeout limits, and dependency-install controls.
  • Define a dependency-free connector manifest and validation helper for #5.
  • Show how a connector can bundle:
    • one or more Python tools;
    • Skills and SKILL.md instructions;
    • MCP server settings;
    • lifecycle hooks;
    • optional memory adapters;
    • optional dependency extras;
    • usage docs and examples.
  • Add at least two connector examples that run without live credentials.
  • Update docs so contributors understand the difference between core primitives, optional connectors, and unsupported marketplace/runtime hosting.
  • Start v1.0 compatibility inventory for public imports, dataclasses, hook phases, trace event names, review-store methods, LightFlow store methods, and memory protocol behavior.

Expected Outcome

LightAgent should have a safer Python execution story, a clearer response to the shared Graph Memory disclosure, and a small but useful extension path for domain integrations, while keeping v1.0 focused on stability instead of new surface area.

Post-v0.9.7 Runtime Workstreams

The earlier plan split runtime evolution across v0.10.0-v0.15.0. These scopes are now consolidated into one public v0.10.0 Unified Event-Sourced Agent Runtime release with six ordered internal milestones:

  1. Session events, stores, replay, projection, and native async execution.
  2. Capability Registry, Provider lifecycle, scopes, and unified Policy.
  3. Durable Inbox, Goals, budgets, steering, and cancellation.
  4. Context compaction, checkpoints, restore, and Session Fork.
  5. Subagents, background Jobs, and Workflow/Agent Loop unification.
  6. Standardized Memory, Skills, MCP, Retrieval, and RAG Providers.

The detailed scope and release gates are maintained in the Near-Term Version Plan. v1.0 is deferred until the complete v0.10.0 runtime has passed its compatibility, replay, recovery, security, and stabilization gates.

Longer-Term Directions

Durable Execution And Resume

  • Add a RunStore interface.
  • Provide SQLite, Redis, and Postgres adapters as optional packages.
  • Persist model requests, responses, tool calls, tool results, memory reads, and memory writes.
  • Add agent.resume(run_id) or flow.resume(run_id).
  • Add idempotency markers for tools.
  • Prevent already-completed tool calls from being repeated during resume.

Structured Output

  • Add output_schema=MyPydanticModel.
  • Validate and parse model output into typed Python objects.
  • Retry or repair invalid JSON where possible.
  • Support schema-first tool and response design.

Data-Oriented Agents

  • Add stronger document, SQL, RAG, and vector-store examples.
  • Provide lightweight adapters for common retrieval workflows.
  • Keep retrieval optional and modular instead of adding heavy core dependencies.

Multi-Agent Protocol Compatibility

  • Continue improving MCP support.
  • Explore agent-to-agent handoff schemas.
  • Evaluate A2A or registry/discovery proposals only as optional connectors.

Visual Debugging

  • Build a simple trace viewer.
  • Show model calls, tool calls, memory operations, handoffs, flow steps, and failures in chronological order.
  • Make traces shareable for issue reports and debugging.

Hook-Based Extensions

  • Keep hooks as a runtime extension contract, not a general plugin marketplace.
  • Prefer small Python callables and dataclass-style context objects over heavy dependency injection.
  • Let hooks power optional integrations for observability, evaluation, enterprise policy, model routing, rate limiting, and audit export.
  • Keep hook payloads explicit and redaction-friendly so trace output does not accidentally expose private prompts, memory values, or tool parameters.
  • Provide compatibility adapters so current guardrail and memory policy users can migrate gradually.

Recommended Priority

Immediate P0

  • Complete the #100 Python Executor security assessment through a private GitHub Security Advisory, and avoid naming affected or fully patched versions until the report is reproduced and the boundary is verified.

Next P1

  • Continue #39 shared Graph Memory validation as an independent security gate, including the opt-in matrix against the exact Mem0 Graph version and storage configuration used in production-like deployments.
  • Begin v0.11.0 with the shared SecurityContext, capability-gating contracts, and the opt-in persistent LightDAG foundation described in the development plan.
  • Keep agent.run("hello"), stream=True, existing Tools, Hooks, Memory, LightSwarm, and LightFlow compatibility behavior stable.

P2

  • Add Provider contract tests for identity, policy, approval, sandbox, credential, network, and cleanup behavior.
  • Evaluate #102 as an optional MemCode adapter without adding a required core dependency or bypassing MemoryPolicy and memory lifecycle hooks.
  • Keep external Provider examples focused, optional, credential-free in CI, and outside the required core dependency set.

P3

  • Implement v0.12.0 trusted data and supply-chain controls for Prompt Injection, Memory/RAG provenance, Skill/MCP signatures, namespaces, and network egress.
  • Implement v0.13.0 Session integrity, atomic Inbox claims, Job recovery, adversarial security tests, and resource-exhaustion tests.
  • Keep visual trace UI, distributed worker coordination, and hosted services as upper-layer or post-protocol work.

Next Development Recommendation

The current development target is v0.11.0 Dynamic DAG Multi-Agent and Unified Security Context, guided by the development plan. It adds an opt-in persistent task-graph layer while retaining all previously planned v0.11.0 security gates. DAG-specific concurrency and recovery guarantees must ship with the feature. v0.12.0-v0.13.0 continue with broader trusted-data, supply-chain, and adversarial recovery work.

Reasoning:

  • The Python Executor report is a direct security boundary concern and must be resolved before adding more execution capabilities or declaring v1.0 ready.
  • The model must be able to propose a capability call, but it must not be able to grant itself permission or alter approval, sandbox, credential, or network policy.
  • Timeout, cancellation, retry, and fallback semantics must not create hidden duplicate side effects in long-running workflows.
  • Security decisions need durable identity, policy version, approval binding, provenance, and audit records so they remain verifiable after restart.
  • The staged v0.10.1-v0.13.0 plan keeps the lightweight core while making security and recovery contracts independently reviewable and testable.
  • Optional stores and Providers preserve the lightweight core and let LightWorker or other products supply Browser, Docker, WebUI, and business workflow implementations.

First v0.10.1 implementation slice (released):

  1. Reproduce #100 in an isolated environment without adding exploit payloads to the public test suite, and document the verified boundary privately.
  2. Make arbitrary Python execution opt-in and require a real SandboxProvider; provide a strict safe-expression path for basic calculations.
  3. Add unified capability and approval checks with canonical argument hashes, expiry, one-time use, and policy-version binding.
  4. Add centralized SecretRef resolution and redaction before persistence, tracing, logging, streaming, and child-agent propagation.
  5. Add Session append conflict detection, resource ceilings, and security regression tests across Python 3.10-3.13.