Merge pull request #4 from clawdotnet/codex/harden-agent-runtime

feat: expand parity workflows and harden agent runtime

Author: Telli

README.md

@@ -7,9 +7,9 @@
 
 SharpClaw Code is a C# and .NET-native coding agent runtime for teams building AI developer tools, agentic CLIs, and MCP-enabled workflows.
 
-It combines durable sessions, permission-aware tool execution, provider abstraction, structured telemetry, and an automation-friendly command-line surface in a codebase designed for production-quality .NET systems, not toy demos.
+It combines durable sessions, permission-aware tool execution, provider abstraction, structured telemetry, and an automation-friendly command-line surface in a runtime shaped for real .NET systems: explicit, testable, and operationally legible.
 
-## What SharpClaw Code Is
+## What It Is
 
 SharpClaw Code is an open-source runtime for building and operating coding-agent experiences in the .NET ecosystem.
 
@@ -27,7 +27,7 @@ It is designed for:
 - **Durable runtime model**: sessions, checkpoints, append-only event logs, export/import flows, and recovery-aware orchestration
 - **Safety by default**: permission modes, approval gates, workspace-boundary enforcement, and mediated tool execution
 - **Extensible surface**: providers, MCP servers, plugins, skills, ACP hosting, and runtime commands integrate through explicit seams
-- **Good fit for automation**: JSON-friendly command output, stable operational commands, and a clean CLI-first workflow
+- **Automation-ready interface**: stable JSON output, operational commands, and a clean CLI-first workflow that works for both humans and scripts
 
 ## Quick Start
 
@@ -71,6 +71,23 @@ dotnet run --project src/SharpClaw.Code.Cli -- --output-format json doctor
 
 Built-in REPL slash commands include `/help`, `/status`, `/doctor`, `/session`, `/commands`, `/mode`, `/editor`, `/export`, `/undo`, `/redo`, and `/version`. Use `/help` to see the active command set, including discovered workspace custom commands.
 
+Parity-oriented commands now include:
+
+- `models` / `/models`
+- `usage` / `/usage`
+- `cost` / `/cost`
+- `stats` / `/stats`
+- `connect` / `/connect`
+- `hooks` / `/hooks`
+- `skills` / `/skills`
+- `agents` / `/agents`
+- `todo` / `/todo`
+- `share` / `/share`
+- `unshare` / `/unshare`
+- `compact` / `/compact`
+- `serve` / `/serve`
+- `/sessions` as a friendlier alias over `/session list`
+
 Primary workflow modes:
 
 - `build`: normal coding-agent execution
@@ -89,14 +106,18 @@ Primary workflow modes:
 | Structured telemetry | Emit runtime events and usage signals that support diagnostics, replay, and automation |
 | JSON-friendly CLI | Use the same runtime through human-readable terminal flows or machine-readable command output |
 | Spec workflow mode | Turn prompts into structured requirements, technical design, and task documents for feature proposals |
+| Embedded local server | Expose prompt, session, status, doctor, and share endpoints for editor or automation clients |
+| Config + agent catalog | Layer user/workspace JSONC config with typed agent defaults, tool allowlists, and runtime hooks |
+| Session sharing | Create self-hosted share links and durable sanitized share snapshots under `.sharpclaw/` |
+| Diagnostics context | Surface configured diagnostics sources into prompt context, status, and machine-readable output |
 
 ## Good Fit For
 
 - building a **C# AI coding assistant**
 - running a **local or hosted coding-agent CLI**
 - creating a **.NET MCP client/runtime**
 - adding **session persistence and auditability** to agent workflows
-- experimenting with **Agent Framework-backed orchestration** without pushing core runtime logic into the framework layer
+- building on **Microsoft Agent Framework** without pushing your application core into framework-specific code
 
 ## Solution Layout
 
@@ -145,8 +166,9 @@ dotnet test SharpClawCode.sln --filter "FullyQualifiedName~ParityScenarioTests"
 | `--output-format text\|json` | Human-readable or structured output |
 | `--primary-mode <mode>` | Workflow bias for prompts: `build`, `plan`, or `spec` |
 | `--session <id>` | Reuse a specific SharpClaw session id for prompt execution |
+| `--agent <id>` | Select the active agent for prompt execution |
 
-Subcommands include `prompt`, `repl`, `doctor`, `status`, `session`, `commands`, `mcp`, `plugins`, `acp`, `bridge`, and `version`.
+Subcommands include `prompt`, `repl`, `doctor`, `status`, `session`, `models`, `usage`, `cost`, `stats`, `connect`, `hooks`, `skills`, `agents`, `todo`, `share`, `unshare`, `compact`, `serve`, `commands`, `mcp`, `plugins`, `acp`, `bridge`, and `version`.
 
 ## Documentation Map
 
@@ -167,7 +189,17 @@ Subcommands include `prompt`, `repl`, `doctor`, `status`, `session`, `commands`,
 
 ## Configuration
 
-SharpClaw Code uses the standard .NET configuration stack (`appsettings.json`, environment variables, CLI args). Key configuration sections:
+SharpClaw Code uses both the standard .NET configuration stack (`appsettings.json`, environment variables, CLI args) and layered SharpClaw JSONC config files:
+
+- user config: `~/.config/sharpclaw/config.jsonc` on Unix-like systems
+- Windows user config: `%AppData%\\SharpClaw\\config.jsonc`
+- workspace config: `<workspace>/sharpclaw.jsonc`
+
+Precedence is:
+
+`CLI args > workspace sharpclaw.jsonc > user config.jsonc > appsettings/environment defaults`
+
+Key runtime configuration sections:
 
 | Section | Purpose |
 |---|---|
@@ -177,13 +209,25 @@ SharpClaw Code uses the standard .NET configuration stack (`appsettings.json`, e
 | `SharpClaw:Web` | Web search provider name, endpoint template, user agent |
 | `SharpClaw:Telemetry` | Runtime event ring buffer capacity |
 
+Key `sharpclaw.jsonc` capabilities:
+
+- `shareMode`: `manual`, `auto`, or `disabled`
+- `server`: host, port, and optional public base URL for share links
+- `defaultAgentId`: default prompt agent
+- `agents`: typed agent catalog entries with model defaults, tool allowlists, and instruction appendices
+- `lspServers`: configured diagnostics sources
+- `hooks`: lifecycle hooks for turn/tool/share/server events
+- `connectLinks`: browser entry points for provider or external auth flows
+
 All options are validated at startup via `IValidateOptions` implementations.
 
 ## Current Scope
 
 - The shared tooling layer is permission-aware across the runtime.
-- The current Agent Framework bridge is focused on provider-backed runs rather than a full tool-calling loop inside the framework path.
-- Operational commands support stable JSON output via `--output-format json`, which makes them useful in scripts and automation.
+- The current runtime includes multi-turn provider-backed tool execution, session-backed prompt replay, and durable conversation history.
+- Agent-driven tool calls flow through the same approval and allowlist enforcement path used by direct tool execution, including caller-aware interactive approval behavior.
+- Operational commands support stable JSON output via `--output-format json`, which makes them suitable for scripts, editors, and automation.
+- The embedded server exposes local JSON and SSE endpoints for prompts, sessions, sharing, status, and doctor flows.
 
 ## Contributing
 

docs/architecture.md

@@ -40,7 +40,7 @@ Test projects: **UnitTests**, **IntegrationTests**, **MockProvider**, **ParityHa
 4. **`SharpClawAgentBase`** delegates to **`AgentFrameworkBridge.RunAsync`**, which drives **`ProviderBackedAgentKernel`** (streaming `IModelProvider`, auth checks, **`ProviderExecutionException`** on hard failures).
 5. Turn completion updates session, checkpoints as implemented in **`ConversationRuntime`**, publishes events via **`IRuntimeEventPublisher`**.
 
-**Note:** `AgentRunContext` carries **`IToolExecutor`**, but the current **`AgentFrameworkBridge`** path does not attach SharpClaw tools to the Microsoft Agent Framework chat loop; **`AgentRunResult.ToolResults`** is empty in that bridge. Tools are still fully usable via **`IToolExecutor`** (tests and parity harness call it directly).
+**Note:** `AgentRunContext` carries **`IToolExecutor`**, and the current **`AgentFrameworkBridge`** path advertises the resolved tool set to the provider, executes tool calls through the permission-aware executor, and records tool results in the agent run result. Prompt references and tool approvals respect the caller's normalized interactivity mode.
 
 ### Operational commands
 

docs/runtime.md

@@ -3,7 +3,7 @@
 The **runtime** layer is centered on **`SharpClaw.Code.Runtime`** and especially **`ConversationRuntime`**, which implements:
 
 - Session surface on **`IConversationRuntime`** — create/get session, **`RunPromptAsync`**
-- **`IRuntimeCommandService`** — **`ExecutePromptAsync`**, **`GetStatusAsync`**, **`RunDoctorAsync`**, **`InspectSessionAsync`**
+- **`IRuntimeCommandService`** — prompt execution plus status, doctor, session inspection, share/unshare, and compaction commands
 
 Registration: `RuntimeServiceCollectionExtensions.AddSharpClawRuntime`.
 
@@ -15,6 +15,13 @@ Registration: `RuntimeServiceCollectionExtensions.AddSharpClawRuntime`.
 2. Maps **`RunPromptRequest`** + session into **`AgentRunContext`** (session/turn ids, working directory, permission mode, output format, **`IToolExecutor`**, metadata).
 3. Invokes **`PrimaryCodingAgent.RunAsync`**.
 
+Before the agent runs, **`ConversationRuntime`** also layers in:
+
+- merged SharpClaw JSONC config (`ISharpClawConfigService`)
+- resolved agent defaults (`IAgentCatalogService`)
+- persisted active-agent metadata from the session, when present
+- auto-share policy checks (`ShareMode.Auto`)
+
 The agent stack is described in [agents.md](agents.md).
 
 ## Lifecycle and state
@@ -24,7 +31,9 @@ The agent stack is described in [agents.md](agents.md).
 
 ## Context assembly
 
-**`PromptContextAssembler`** pulls workspace/session-aware data (skills registry, memory hooks, git context as wired today) into the prompt path before the agent runs.
+**`PromptContextAssembler`** pulls workspace/session-aware data (skills registry, todo state, memory hooks, git context as wired today) into the prompt path before the agent runs.
+
+It also includes a compact diagnostics summary from **`IWorkspaceDiagnosticsService`**, which currently surfaces configured diagnostics sources and build-derived findings for .NET workspaces.
 
 When the effective **`PrimaryMode`** is **`Spec`**, the assembler appends a structured output contract that requires the model to return machine-readable requirements, design, and task content.
 
@@ -50,6 +59,41 @@ Each spec-mode prompt creates a fresh folder. If the same slug already exists, t
 
 Used by **`GetStatusAsync`**, **`RunDoctorAsync`**, and **`InspectSessionAsync`** to build **Protocol** reports (`DoctorReport`, `RuntimeStatusReport`, `SessionInspectionReport`).
 
+`RuntimeStatusReport` now also carries:
+
+- configured diagnostics source count
+- current diagnostic error count
+- current diagnostic warning count
+
+## Config, agents, and hooks
+
+The parity layer adds several runtime-owned services:
+
+- **`ISharpClawConfigService`** — loads user/workspace `config.jsonc` + `sharpclaw.jsonc` and merges them by precedence
+- **`IAgentCatalogService`** — overlays configured specialist agents on top of built-in agents
+- **`IConversationCompactionService`** — creates durable session summaries stored in session metadata
+- **`IShareSessionService`** — creates and removes self-hosted share snapshots
+- **`IHookDispatcher`** — executes configured hook processes for turn/tool/share/server events and exposes hook inspection/testing
+- **`ITodoService`** — persists session and workspace todo items under session metadata and `.sharpclaw/tasks.json`
+- **`IWorkspaceInsightsService`** — reconstructs durable usage, cost, and execution stats from persisted event logs
+
+These services are intentionally small and runtime-owned rather than separate orchestration subsystems.
+
+## Embedded server
+
+**`IWorkspaceHttpServer`** / **`WorkspaceHttpServer`** expose a minimal local HTTP surface for editor and automation clients:
+
+- `POST /v1/prompt`
+- `GET /v1/sessions`
+- `GET /v1/sessions/{id}`
+- `POST /v1/share/{sessionId}`
+- `DELETE /v1/share/{sessionId}`
+- `GET /v1/status`
+- `GET /v1/doctor`
+- `GET /s/{shareId}`
+
+Prompt requests can return JSON or replay the completed runtime event stream as SSE.
+
 ## Hosted service
 
 **`RuntimeCoordinatorHostedServiceAdapter`** is registered as **`IHostedService`** and currently logs start/stop only (placeholder for future lifecycle coordination).
@@ -62,3 +106,7 @@ Used by **`GetStatusAsync`**, **`RunDoctorAsync`**, and **`InspectSessionAsync`*
 | `DefaultTurnRunner` | `src/SharpClaw.Code.Runtime/Turns/DefaultTurnRunner.cs` |
 | `OperationalDiagnosticsCoordinator` | `src/SharpClaw.Code.Runtime/Diagnostics/OperationalDiagnosticsCoordinator.cs` |
 | `IRuntimeCommandService` | `src/SharpClaw.Code.Runtime/Abstractions/IRuntimeCommandService.cs` |
+| `SharpClawConfigService` | `src/SharpClaw.Code.Runtime/Configuration/SharpClawConfigService.cs` |
+| `ShareSessionService` | `src/SharpClaw.Code.Runtime/Workflow/ShareSessionService.cs` |
+| `ConversationCompactionService` | `src/SharpClaw.Code.Runtime/Workflow/ConversationCompactionService.cs` |
+| `WorkspaceHttpServer` | `src/SharpClaw.Code.Runtime/Server/WorkspaceHttpServer.cs` |

src/SharpClaw.Code.Acp/AcpStdioHost.cs

@@ -190,7 +190,8 @@ private async Task<JsonObject> HandleSessionPromptAsync(
                     WorkingDirectory: workspace,
                     PermissionMode: PermissionMode.WorkspaceWrite,
                     OutputFormat: OutputFormat.Json,
-                    Metadata: new Dictionary<string, string> { ["acp"] = "true" }),
+                    Metadata: new Dictionary<string, string> { ["acp"] = "true" },
+                    IsInteractive: false),
                 cancellationToken)
             .ConfigureAwait(false);
 

src/SharpClaw.Code.Agents/Agents/SharpClawAgentBase.cs

@@ -1,5 +1,6 @@
 using SharpClaw.Code.Agents.Abstractions;
 using SharpClaw.Code.Agents.Models;
+using SharpClaw.Code.Protocol.Models;
 
 namespace SharpClaw.Code.Agents.Agents;
 
@@ -31,13 +32,23 @@ public abstract class SharpClawAgentBase(IAgentFrameworkBridge agentFrameworkBri
 
     /// <inheritdoc />
     public virtual Task<AgentRunResult> RunAsync(AgentRunContext context, CancellationToken cancellationToken)
-        => agentFrameworkBridge.RunAsync(
+    {
+        var instructions = Instructions;
+        if (context.Metadata is not null
+            && context.Metadata.TryGetValue(SharpClawWorkflowMetadataKeys.AgentInstructionAppendix, out var appendix)
+            && !string.IsNullOrWhiteSpace(appendix))
+        {
+            instructions = $"{instructions}{Environment.NewLine}{Environment.NewLine}{appendix.Trim()}";
+        }
+
+        return agentFrameworkBridge.RunAsync(
             new AgentFrameworkRequest(
                 AgentId,
                 AgentKind,
                 Name,
                 Description,
-                Instructions,
+                instructions,
                 context),
             cancellationToken);
+    }
 }

src/SharpClaw.Code.Agents/Internal/ProviderBackedAgentKernel.cs

@@ -126,7 +126,8 @@ internal async Task<ProviderInvocationResult> ExecuteAsync(
             UsageSnapshot? terminalUsage = null;
             ProviderRequest? lastProviderRequest = null;
 
-            for (var iteration = 0; iteration < options.MaxToolIterations; iteration++)
+            var iteration = 0;
+            for (; iteration < options.MaxToolIterations; iteration++)
             {
                 UsageSnapshot? iterationUsage = null;
 
@@ -252,6 +253,16 @@ internal async Task<ProviderInvocationResult> ExecuteAsync(
                 }
             }
 
+            // Detect if the loop was exhausted (provider kept requesting tools every iteration).
+            if (iteration >= options.MaxToolIterations)
+            {
+                logger.LogWarning(
+                    "Tool-calling loop reached maximum iterations ({MaxIterations}) for session {SessionId}; output may be incomplete.",
+                    options.MaxToolIterations,
+                    request.Context.SessionId);
+                outputSegments.Add($"\n\n[Tool-calling loop reached the maximum of {options.MaxToolIterations} iterations. Output may be incomplete.]");
+            }
+
             var output = string.Concat(outputSegments);
             if (string.IsNullOrWhiteSpace(output))
             {

src/SharpClaw.Code.Agents/Internal/ToolCallDispatcher.cs

@@ -1,6 +1,5 @@
 using SharpClaw.Code.Protocol.Events;
 using SharpClaw.Code.Protocol.Models;
-using SharpClaw.Code.Telemetry.Abstractions;
 using SharpClaw.Code.Tools.Abstractions;
 using SharpClaw.Code.Tools.Models;
 
@@ -11,8 +10,7 @@ namespace SharpClaw.Code.Agents.Internal;
 /// and returns content blocks for the provider conversation.
 /// </summary>
 public sealed class ToolCallDispatcher(
-    IToolExecutor toolExecutor,
-    IRuntimeEventPublisher eventPublisher)
+    IToolExecutor toolExecutor)
 {
     /// <summary>
     /// Executes a tool call and returns a tool-result content block.
@@ -38,34 +36,11 @@ public sealed class ToolCallDispatcher(
         var toolInputJson = toolUseEvent.ToolInputJson ?? "{}";
         var toolUseId = toolUseEvent.ToolUseId;
 
-        var collectedEvents = new List<RuntimeEvent>();
-
-        // 1. Execute the tool (this builds the real ToolExecutionRequest internally with correct approval/destructive metadata)
+        // Execute the tool — ToolExecutor already publishes ToolStartedEvent and ToolCompletedEvent
+        // via IRuntimeEventPublisher, so we do NOT re-publish here to avoid duplicates.
         var envelope = await toolExecutor.ExecuteAsync(toolName, toolInputJson, context, cancellationToken);
 
-        // 2. Publish ToolStartedEvent using the real request from the executor (has correct approval scope, destructive flag, etc.)
-        var startedEvent = new ToolStartedEvent(
-            EventId: $"event-{Guid.NewGuid():N}",
-            SessionId: context.SessionId,
-            TurnId: context.TurnId,
-            OccurredAtUtc: DateTimeOffset.UtcNow,
-            Request: envelope.Request);
-
-        await eventPublisher.PublishAsync(startedEvent, cancellationToken: cancellationToken);
-        collectedEvents.Add(startedEvent);
-
-        // 3. Publish ToolCompletedEvent
-        var completedEvent = new ToolCompletedEvent(
-            EventId: $"event-{Guid.NewGuid():N}",
-            SessionId: context.SessionId,
-            TurnId: context.TurnId,
-            OccurredAtUtc: DateTimeOffset.UtcNow,
-            Result: envelope.Result);
-
-        await eventPublisher.PublishAsync(completedEvent, cancellationToken: cancellationToken);
-        collectedEvents.Add(completedEvent);
-
-        // 4. Convert ToolResult to ContentBlock
+        // Convert ToolResult to ContentBlock
         ContentBlock resultBlock;
         if (envelope.Result.Succeeded)
         {
@@ -88,7 +63,7 @@ public sealed class ToolCallDispatcher(
                 true);
         }
 
-        // 5. Return
-        return (resultBlock, envelope.Result, collectedEvents);
+        // Events are already published by ToolExecutor; return empty list to avoid duplicates.
+        return (resultBlock, envelope.Result, []);
     }
 }

src/SharpClaw.Code.Agents/Models/AgentRunContext.cs

@@ -24,6 +24,7 @@ namespace SharpClaw.Code.Agents.Models;
 /// Prior-turn messages assembled from session events. When non-empty these are prepended
 /// to the provider request so the model has multi-turn context.
 /// </param>
+/// <param name="IsInteractive">Whether tool approvals can interact with the caller.</param>
 public sealed record AgentRunContext(
     string SessionId,
     string TurnId,
@@ -38,4 +39,5 @@ public sealed record AgentRunContext(
     DelegatedTaskContract? DelegatedTask = null,
     PrimaryMode PrimaryMode = PrimaryMode.Build,
     IToolMutationRecorder? ToolMutationRecorder = null,
-    IReadOnlyList<ChatMessage>? ConversationHistory = null);
+    IReadOnlyList<ChatMessage>? ConversationHistory = null,
+    bool IsInteractive = true);