F3: Work products / deliverables as first-class objects

app/Http/Controllers/Api/DaemonController.php

@@ -15,6 +15,7 @@
 use App\Models\Approval;
 use App\Models\Server;
 use App\Models\Task;
+use App\Models\TaskWorkProduct;
 use App\Models\UsageEvent;
 use App\Services\AuditService;
 use App\Services\TaskCheckoutService;
@@ -170,6 +171,21 @@ public function reportResult(ReportResultRequest $request, string $token, Task $
             ]);
         }
 
+        // Create work product records
+        if (! empty($validated['work_products'])) {
+            foreach ($validated['work_products'] as $wp) {
+                TaskWorkProduct::query()->create([
+                    'task_id' => $task->id,
+                    'agent_id' => $task->agent_id,
+                    'type' => $wp['type'] ?? 'file',
+                    'title' => $wp['title'],
+                    'file_path' => $wp['file_path'] ?? null,
+                    'url' => $wp['url'] ?? null,
+                    'summary' => $wp['summary'] ?? null,
+                ]);
+            }
+        }
+
         // Process delegations — create sub-tasks for named direct reports
         if (! empty($validated['delegations']) && $task->agent?->delegation_enabled) {
             foreach ($validated['delegations'] as $delegation) {

app/Http/Controllers/GovernanceTaskController.php

@@ -96,6 +96,7 @@ public function show(Request $request, Task $task): Response
             'parentTask',
             'subTasks.agent',
             'usageEvents',
+            'workProducts',
         ]);
 
         $auditEntries = $task->team->auditLogs()

app/Http/Controllers/TaskWorkProductController.php

@@ -0,0 +1,84 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Enums\HarnessType;
+use App\Models\Task;
+use App\Models\TaskWorkProduct;
+use App\Services\SshService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use RuntimeException;
+use Symfony\Component\HttpFoundation\StreamedResponse;
+
+class TaskWorkProductController extends Controller
+{
+    public function __construct(private readonly SshService $sshService) {}
+
+    /**
+     * Download a work product file from the agent's workspace on the server.
+     */
+    public function download(Request $request, Task $task, TaskWorkProduct $taskWorkProduct): StreamedResponse|JsonResponse
+    {
+        abort_unless($task->team_id === $request->user()->current_team_id, 403);
+        abort_unless($taskWorkProduct->task_id === $task->id, 404);
+        abort_unless($taskWorkProduct->file_path, 404, 'Work product has no file path.');
+
+        $agent = $task->agent;
+        abort_unless($agent, 404, 'Task has no assigned agent.');
+
+        $server = $agent->server;
+        abort_unless($server, 404, 'Agent has no server.');
+
+        $basePath = $agent->harness_type === HarnessType::Hermes
+            ? "/root/.hermes-{$agent->harness_agent_id}/workspace/"
+            : "/root/.openclaw/agents/{$agent->harness_agent_id}/";
+
+        $filePath = $this->sanitizePath($taskWorkProduct->file_path);
+
+        if (! $filePath) {
+            return response()->json(['message' => 'Invalid file path.'], 422);
+        }
+
+        $fullPath = $basePath.$filePath;
+
+        $this->sshService->connect($server);
+
+        try {
+            $content = $this->sshService->readFile($fullPath);
+        } catch (RuntimeException) {
+            $this->sshService->disconnect();
+
+            return response()->json(['message' => 'File not found on server.'], 404);
+        } finally {
+            $this->sshService->disconnect();
+        }
+
+        $filename = basename($filePath);
+
+        return response()->streamDownload(function () use ($content) {
+            echo $content;
+        }, $filename);
+    }
+
+    /**
+     * Sanitize a file path to prevent directory traversal.
+     */
+    private function sanitizePath(string $path): string
+    {
+        $path = str_replace("\0", '', $path);
+        $path = str_replace('\\', '/', $path);
+        $path = ltrim($path, '/');
+
+        $segments = explode('/', $path);
+        $clean = [];
+        foreach ($segments as $segment) {
+            if ($segment === '' || $segment === '.' || $segment === '..') {
+                continue;
+            }
+            $clean[] = $segment;
+        }
+
+        return implode('/', $clean);
+    }
+}

app/Http/Requests/Governance/ReportResultRequest.php

@@ -33,6 +33,12 @@ public function rules(): array
             'approval_requests.*.type' => ['required_with:approval_requests', 'string'],
             'approval_requests.*.title' => ['required_with:approval_requests', 'string', 'max:255'],
             'approval_requests.*.payload' => ['nullable', 'array'],
+            'work_products' => ['nullable', 'array'],
+            'work_products.*.title' => ['required_with:work_products', 'string', 'max:255'],
+            'work_products.*.file_path' => ['nullable', 'string', 'max:1000'],
+            'work_products.*.url' => ['nullable', 'string', 'max:2000'],
+            'work_products.*.type' => ['nullable', 'string', 'max:50'],
+            'work_products.*.summary' => ['nullable', 'string', 'max:5000'],
         ];
     }
 }

app/Models/Task.php

@@ -129,6 +129,14 @@ public function delegatedByAgent(): BelongsTo
         return $this->belongsTo(Agent::class, 'delegated_by');
     }
 
+    /**
+     * @return HasMany<TaskWorkProduct, $this>
+     */
+    public function workProducts(): HasMany
+    {
+        return $this->hasMany(TaskWorkProduct::class);
+    }
+
     /**
      * @return HasMany<UsageEvent, $this>
      */

app/Models/TaskWorkProduct.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Concerns\HasUlids;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class TaskWorkProduct extends Model
+{
+    use HasFactory, HasUlids;
+
+    /**
+     * @var list<string>
+     */
+    protected $fillable = [
+        'task_id',
+        'agent_id',
+        'type',
+        'title',
+        'file_path',
+        'url',
+        'summary',
+    ];
+
+    /**
+     * @return BelongsTo<Task, $this>
+     */
+    public function task(): BelongsTo
+    {
+        return $this->belongsTo(Task::class);
+    }
+
+    /**
+     * @return BelongsTo<Agent, $this>
+     */
+    public function agent(): BelongsTo
+    {
+        return $this->belongsTo(Agent::class);
+    }
+}

database/factories/TaskWorkProductFactory.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Database\Factories;
+
+use App\Models\Agent;
+use App\Models\Task;
+use App\Models\TaskWorkProduct;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/**
+ * @extends Factory<TaskWorkProduct>
+ */
+class TaskWorkProductFactory extends Factory
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function definition(): array
+    {
+        return [
+            'task_id' => Task::factory(),
+            'agent_id' => Agent::factory(),
+            'type' => 'file',
+            'title' => fake()->sentence(3),
+            'file_path' => '/workspace/output/'.fake()->slug().'.md',
+            'summary' => fake()->paragraph(),
+        ];
+    }
+}

database/migrations/2026_04_08_220001_create_task_work_products_table.php

@@ -0,0 +1,30 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('task_work_products', function (Blueprint $table) {
+            $table->ulid('id')->primary();
+            $table->foreignUlid('task_id')->constrained('tasks')->cascadeOnDelete();
+            $table->foreignUlid('agent_id')->nullable()->constrained('agents')->nullOnDelete();
+            $table->string('type')->default('file');
+            $table->string('title');
+            $table->text('file_path')->nullable();
+            $table->text('url')->nullable();
+            $table->text('summary')->nullable();
+            $table->timestamps();
+
+            $table->index('task_id');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('task_work_products');
+    }
+};

packages/provisiond/bundle/provisiond.mjs

@@ -206,6 +206,7 @@ function buildPrompt(task) {
   lines.push("");
   lines.push("## Instructions");
   lines.push("Complete this task. You have access to your browser, terminal, and workspace.");
+  lines.push("Save files others need to ./shared/. Keep work-in-progress in your private workspace.");
   lines.push("");
   lines.push("When done, provide a summary of what you accomplished.");
   if (directReports.length > 0) {
@@ -216,17 +217,22 @@ function buildPrompt(task) {
   lines.push("");
   lines.push("To request approval for a high-impact action:");
   lines.push("APPROVAL_REQUEST: {type} | {title} | {description}");
+  lines.push("");
+  lines.push("To declare a file or deliverable you produced:");
+  lines.push("WORK_PRODUCT: {title} | {file_path} | {summary}");
   return lines.join("\n");
 }
 
 // src/response-parser.ts
 var DELEGATE_PREFIX = "DELEGATE:";
 var APPROVAL_PREFIX = "APPROVAL_REQUEST:";
+var WORK_PRODUCT_PREFIX = "WORK_PRODUCT:";
 function parseResponse(text) {
   const lines = text.split("\n");
   const summaryLines = [];
   const delegations = [];
   const approvalRequests = [];
+  const workProducts = [];
   for (const line of lines) {
     const trimmed = line.trim();
     if (trimmed.startsWith(DELEGATE_PREFIX)) {
@@ -249,10 +255,20 @@ function parseResponse(text) {
       }
       continue;
     }
+    if (trimmed.startsWith(WORK_PRODUCT_PREFIX)) {
+      const workProduct = parseWorkProduct(trimmed.slice(WORK_PRODUCT_PREFIX.length).trim());
+      if (workProduct) {
+        workProducts.push(workProduct);
+      } else {
+        logger.warn("Malformed WORK_PRODUCT line, including in summary", { line: trimmed });
+        summaryLines.push(line);
+      }
+      continue;
+    }
     summaryLines.push(line);
   }
   const resultSummary = summaryLines.join("\n").trim();
-  return { resultSummary, delegations, approvalRequests };
+  return { resultSummary, delegations, approvalRequests, workProducts };
 }
 function parseDelegation(raw) {
   const parts = raw.split("|").map((s) => s.trim());
@@ -276,6 +292,17 @@ function parseApproval(raw) {
     description: parts.slice(2).join(" | ")
   };
 }
+function parseWorkProduct(raw) {
+  const parts = raw.split("|").map((s) => s.trim());
+  if (parts.length < 1 || !parts[0]) {
+    return null;
+  }
+  return {
+    title: parts[0],
+    filePath: parts[1] || void 0,
+    summary: parts.length > 2 ? parts.slice(2).join(" | ") : void 0
+  };
+}
 
 // src/executor.ts
 var OPENCLAW_DEFAULT_PORT = 18789;
@@ -323,6 +350,12 @@ async function executeTask(task, config, api) {
         type: a.type,
         title: a.title,
         description: a.description
+      })),
+      work_products: parsed.workProducts.map((wp) => ({
+        title: wp.title,
+        file_path: wp.filePath,
+        type: "file",
+        summary: wp.summary
       }))
     };
     await api.reportResult(task.id, result);