artifact

package
v0.12.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 10, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package artifact owns session-scoped deliverables. Workspace artifacts keep their content in the registered workspace; managed artifacts keep validated content below JCode's private artifact root. Persisted metadata never contains an absolute path or file content.

Index

Constants

View Source 
const (
	MaxInlineTextSize   int64 = 5 << 20
	MaxInlineBinarySize int64 = 25 << 20
	MaxDownloadSize     int64 = 250 << 20
	MaxShareSize        int64 = 25 << 20
)

Variables

View Source 
var ErrTooLarge = errors.New("artifact is too large")

Functions

This section is empty.

Types

type Kind 

type Kind string
const (
	KindAuto     Kind = "auto"
	KindText     Kind = "text"
	KindMarkdown Kind = "markdown"
	KindCode     Kind = "code"
	KindHTML     Kind = "html"
	KindImage    Kind = "image"
	KindPDF      Kind = "pdf"
	KindCSV      Kind = "csv"
	KindBinary   Kind = "binary"
)

type Loader 

type Loader func(sessionID string) ([]Record, error)

type ManagedImageRequest added in v0.12.3 

type ManagedImageRequest struct {
	SessionID        string
	Title            string
	Reader           io.Reader
	ProviderID       string
	ModelID          string
	ParentArtifactID string
	OperationID      string
	ToolCallID       string
	Focus            bool

	// Expected values are optional defense-in-depth assertions against metadata
	// supplied by an adapter. The bytes remain the source of truth.
	ExpectedMediaType string
	ExpectedWidth     int
	ExpectedHeight    int
	ExpectedSHA256    string
}

ManagedImageRequest is the only P0 managed-content write contract. The caller supplies bytes, not a path; the service chooses the opaque ID, key, extension, permissions, and final location from validated content.

type Record 

type Record struct {
	ID               string      `json:"id"`
	SessionID        string      `json:"session_id"`
	StorageKind      StorageKind `json:"storage_kind,omitempty"`
	RelativePath     string      `json:"relative_path,omitempty"`
	RelativeKey      string      `json:"relative_key,omitempty"`
	Title            string      `json:"title"`
	Kind             Kind        `json:"kind"`
	MediaType        string      `json:"media_type"`
	Size             int64       `json:"size"`
	Width            int         `json:"width,omitempty"`
	Height           int         `json:"height,omitempty"`
	SHA256           string      `json:"sha256,omitempty"`
	ProviderID       string      `json:"provider_id,omitempty"`
	ModelID          string      `json:"model_id,omitempty"`
	ParentArtifactID string      `json:"parent_artifact_id,omitempty"`
	OperationID      string      `json:"operation_id,omitempty"`
	ToolCallID       string      `json:"tool_call_id,omitempty"`
	Revision         int         `json:"revision"`
	UpdatedAt        time.Time   `json:"updated_at"`
	Status           Status      `json:"status"`
	// Focus is never omitted: false is a deliberate instruction to keep the
	// Artifact unseen without stealing the active panel, while older clients
	// may treat an absent field as the legacy focus=true behavior.
	Focus     bool `json:"focus"`
	Shareable bool `json:"shareable,omitempty"`
}

Record is the metadata persisted in a session entry and exposed to the Web UI. It intentionally contains neither an absolute path nor file content.

func (Record) EffectiveShareable added in v0.12.3 

func (r Record) EffectiveShareable() bool

EffectiveShareable preserves the v1 workspace contract. Workspace Artifacts predate the persisted shareable bit and remain shareable; managed media is fail-closed unless a future storage policy explicitly opts it in.

func (Record) EffectiveStorageKind added in v0.12.3 

func (r Record) EffectiveStorageKind() StorageKind

EffectiveStorageKind preserves the v1 contract: a missing storage_kind is a workspace record, never a managed key guessed from other fields.

func (Record) Ref added in v0.12.3 

func (r Record) Ref() Ref

type Recorder 

type Recorder interface {
	RecordArtifact(Record) error
}

Recorder is the durable boundary. Register never publishes a revision until this append succeeds.

type Ref added in v0.12.3 

type Ref struct {
	ID               string      `json:"id"`
	StorageKind      StorageKind `json:"storage_kind"`
	RelativeKey      string      `json:"relative_key,omitempty"`
	Title            string      `json:"title"`
	Kind             Kind        `json:"kind"`
	MediaType        string      `json:"media_type"`
	Size             int64       `json:"size"`
	Width            int         `json:"width,omitempty"`
	Height           int         `json:"height,omitempty"`
	SHA256           string      `json:"sha256,omitempty"`
	ProviderID       string      `json:"provider_id,omitempty"`
	ModelID          string      `json:"model_id,omitempty"`
	ParentArtifactID string      `json:"parent_artifact_id,omitempty"`
	OperationID      string      `json:"operation_id,omitempty"`
	ToolCallID       string      `json:"tool_call_id,omitempty"`
	Shareable        bool        `json:"shareable,omitempty"`
}

Ref is the transport-safe, path-free projection returned by tools and live events. Content remains accessible only through Service.Open/Resolve.

type RegisterRequest 

type RegisterRequest struct {
	SessionID    string
	Workspace    string
	RelativePath string
	Title        string
	Kind         Kind
	Focus        bool
}

type Service 

type Service struct {
	// contains filtered or unexported fields
}

func NewService 

func NewService(loader Loader, now func() time.Time) *Service

func NewServiceWithManagedRoot added in v0.12.3 

func NewServiceWithManagedRoot(loader Loader, now func() time.Time, managedRoot string) *Service

NewServiceWithManagedRoot is intended for isolated runtimes and tests. The supplied path is the trusted root itself; callers must not derive it from a model or HTTP request.

func (*Service) CreateManagedImage added in v0.12.3 

func (s *Service) CreateManagedImage(
	ctx context.Context,
	req ManagedImageRequest,
	recorder Recorder,
) (Record, error)

CreateManagedImage validates and atomically stores one generated image. If metadata persistence fails after the rename, the returned Record identifies the preserved orphan for diagnostics; it is intentionally not removed and not published into the in-memory registry.

func (*Service) List 

func (s *Service) List(ctx context.Context, sessionID, workspace string) ([]Record, error)

func (*Service) ListManaged added in v0.12.3 

func (s *Service) ListManaged(ctx context.Context, sessionID string) ([]Record, error)

ListManaged returns only content rooted under JCode's private managed storage. It intentionally accepts no workspace path, making it safe for an SSH/Docker task whose workspace path belongs to a different host.

func (*Service) Open 

func (s *Service) Open(ctx context.Context, sessionID, workspace, artifactID string) (Record, *os.File, error)

Open returns a read-only file descriptor constrained by os.Root. Unlike a validate-then-os.Open sequence, Root.Open prevents a concurrent symlink swap from redirecting the read outside the workspace.

func (*Service) Register 

func (s *Service) Register(ctx context.Context, req RegisterRequest, recorder Recorder) (Record, error)

func (*Service) Resolve 

func (s *Service) Resolve(ctx context.Context, sessionID, workspace, artifactID string) (Record, string, error)

Resolve revalidates a registered artifact at the time of use and returns its server-only absolute path. Callers must never serialize absolutePath.

type Status 

type Status string
const (
	StatusAvailable   Status = "available"
	StatusMissing     Status = "missing"
	StatusUnsupported Status = "unsupported"
	StatusTooLarge    Status = "too_large"
	StatusError       Status = "error"
)

type StorageKind added in v0.12.3 

type StorageKind string

StorageKind identifies the trusted backend used for an artifact. The empty value is deliberately interpreted as workspace so records written by older JCode versions retain their original behavior. 

const (
	StorageWorkspace StorageKind = "workspace"
	StorageManaged   StorageKind = "managed"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.