php-agentic/Models/AgentWorkspaceState.php

<?php

declare(strict_types=1);

namespace Core\Mod\Agentic\Models;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

/**
 * Agent Workspace State - shared context between sessions within a plan.
 *
 * Stores key-value data that persists across agent sessions,
 * enabling context sharing and state recovery.
 *
 * @property int $id
 * @property int $agent_plan_id
 * @property string $key
 * @property array $value
 * @property string $type
 * @property string|null $description
 * @property \Carbon\Carbon|null $created_at
 * @property \Carbon\Carbon|null $updated_at
 */
class AgentWorkspaceState extends Model
{
    protected $table = 'agent_workspace_states';

    protected $fillable = [
        'agent_plan_id',
        'key',
        'value',
        'type',
        'description',
    ];

    protected $casts = [
        'value' => 'array',
    ];

    // Type constants
    public const TYPE_JSON = 'json';

    public const TYPE_MARKDOWN = 'markdown';

    public const TYPE_CODE = 'code';

    public const TYPE_REFERENCE = 'reference';

    // Relationships
    public function plan(): BelongsTo
    {
        return $this->belongsTo(AgentPlan::class, 'agent_plan_id');
    }

    // Scopes
    public function scopeForPlan(Builder $query, AgentPlan|int $plan): Builder
    {
        $planId = $plan instanceof AgentPlan ? $plan->id : $plan;

        return $query->where('agent_plan_id', $planId);
    }

    public function scopeOfType(Builder $query, string $type): Builder
    {
        return $query->where('type', $type);
    }

    // Helpers
    public function isJson(): bool
    {
        return $this->type === self::TYPE_JSON;
    }

    public function isMarkdown(): bool
    {
        return $this->type === self::TYPE_MARKDOWN;
    }

    public function isCode(): bool
    {
        return $this->type === self::TYPE_CODE;
    }

    public function isReference(): bool
    {
        return $this->type === self::TYPE_REFERENCE;
    }

    public function getValue(): mixed
    {
        return $this->value;
    }

    public function getFormattedValue(): string
    {
        if ($this->isMarkdown() || $this->isCode()) {
            return is_string($this->value) ? $this->value : json_encode($this->value, JSON_PRETTY_PRINT);
        }

        return json_encode($this->value, JSON_PRETTY_PRINT);
    }

    // Output
    public function toMcpContext(): array
    {
        return [
            'key' => $this->key,
            'type' => $this->type,
            'description' => $this->description,
            'value' => $this->value,
            'updated_at' => $this->updated_at?->toIso8601String(),
        ];
    }
}