Documentation
¶
Index ¶
- Constants
- Variables
- func ApplyUserPromptRequestedPath(media []chat.MediaDelta, prompt string)
- func ExtractExplicitOutputFilename(prompt string) (string, bool)
- func SanitizeMimeType(mimeType string) string
- func SaveFailureReason(err error) string
- type GeneratedFileRef
- type ResolvedGeneratedFile
- type Service
Constants ¶
const ( FallbackDisplayName = "generated media" FallbackMimeType = "application/octet-stream" )
FallbackDisplayName and FallbackMimeType are the canonical, deterministic substitutes used whenever a provider supplies an empty, unnamed, or syntactically invalid display name or MIME type. Every caller that surfaces this metadata (placeholders, warnings) must use exactly these values rather than inventing its own fallback text.
const MaxWarningBytes = 512
MaxWarningBytes bounds every fully formatted placeholder or warning line after interpolation, independent of the smaller chat.MaxSanitizedFieldBytes bound already applied to each individual name/MIME field: it is a defense-in-depth backstop against amplification through combined/duplicated fields, not something normal (already field-bounded) input is expected to hit.
const RetryWithDebugAdvice = "Enable --debug and retry to capture technical details."
RetryWithDebugAdvice is the user-facing fallback for a generated-media save failure with no safe classified reason: it tells the user how to capture the technical details instead of leaking any of them.
Variables ¶
ErrGeneratedFileUnavailable is the single caller-visible failure of [LocalRuntime.ResolveGeneratedFile]. Every refusal — unknown root kind, missing manifest record, root-kind mismatch, workspace escape, symlink replacement, or missing file — collapses into it so UIs can only ever say "unavailable"; the wrapped cause is for debug logs.
Functions ¶
func ApplyUserPromptRequestedPath ¶
func ApplyUserPromptRequestedPath(media []chat.MediaDelta, prompt string)
ApplyUserPromptRequestedPath fills RequestedPath from the triggering user prompt for a turn that returned exactly ONE media blob that marker pairing left unnamed. Markers keep precedence (a non-empty RequestedPath is never overwritten) and multi-blob turns are skipped entirely — a single prompt filename cannot unambiguously name one blob among several.
func ExtractExplicitOutputFilename ¶
ExtractExplicitOutputFilename returns the single unambiguous explicit output filename in the triggering user prompt, if there is exactly one. Candidates that fail validation (unknown extension, control characters, invalid UTF-8, over-long, extension-only, comparative of-phrase) are ignored rather than counted. The two grammars overlap: an of-phrase subject may swallow a conjunction ahead of an explicit cue ("make a logo of a wolf and save it as logo.png"), so candidates are keyed by the filename capture's position — the same occurrence matched by both grammars counts once, while distinct occurrences (even of the same name) stay ambiguous and yield no extraction.
func SanitizeMimeType ¶
SanitizeMimeType is chat.SanitizeDisplayName's narrower counterpart for a MIME type value: control characters and newlines are neutralized first, the result is capped at chat.MaxSanitizedFieldBytes, and it must then match [mimeTypePattern] — a bare, conservative type/subtype pair — or the entire value is discarded in favor of FallbackMimeType. This is stricter than chat.SanitizeDisplayName (which rewrites individual bad characters and keeps the rest): a MIME type has no legitimate free-text content, so anything that fails the conservative syntax check is untrustworthy as a whole, not just in the specific characters it used to smuggle a fake log line or escape sequence.
func SaveFailureReason ¶
SaveFailureReason maps a generated-media save failure to a fixed, user-safe sentence for the runtime WarningEvent. Every return value is a constant: nothing from err — which may embed the absolute workspace root, a requested path, a session ID, or raw OS error text — ever reaches the warning. The detailed error belongs in the debug log only.
Types ¶
type GeneratedFileRef ¶
type GeneratedFileRef struct {
// OwnerSessionID is the session the file was materialized under — the
// owning session, never the viewing one.
OwnerSessionID string
// Root is the root kind Path is interpreted against. Only
// chat.ArtifactRootWorkspace resolves; all other kinds are unavailable.
Root chat.ArtifactRootKind
// Path is the recorded workspace-relative slash-separated final path.
Path string
}
GeneratedFileRef identifies one persisted generated-media reference, as carried by chat.DocumentSource (ArtifactPath/ArtifactRoot/ ArtifactOwnerSessionID).
type ResolvedGeneratedFile ¶
ResolvedGeneratedFile carries the resolved bytes and a display path. Portable blobs remain readable without workspace provenance; in that case Path is the recorded relative artifact path, not a canonical absolute path.
type Service ¶
type Service struct {
Store session.Store
Now func() time.Time
Write func(string, string, []byte, string) (workspacemedia.Result, error)
// contains filtered or unexported fields
}
Service stores and resolves generated media under its owning session. Store, Now, and Write are fixed before use; cached provenance is concurrency-safe.
func (*Service) Materialize ¶
func (r *Service) Materialize(ctx context.Context, sess *session.Session, media []chat.MediaDelta, agentName string, warn func(string)) []chat.MessagePart
Materialize writes each streamed chat.MediaDelta into the owning session's workspace (the effective WorkingDir resolved via session.ResolveWorkingDir) through workspacemedia.Write and returns the corresponding document parts, so the persisted assistant message keeps only a relative, owner-qualified workspace reference (chat.ArtifactRootWorkspace) rather than raw bytes. sess.ID becomes the reference's permanent owner (see chat.DocumentSource) — it never changes even if this message is later copied into a branched or forked session. Each successful write is also recorded in the session store's generated-media manifest (session.GeneratedMediaManifest), the trust anchor a resolver must consult before reading a workspace path back.
The requested filename is the prompt-directed path when one exists (chat.MediaDelta.RequestedPath, populated by media-file marker pairing in handleStream, or — for a turn whose single blob no marker named — by deterministic explicit-filename extraction from the triggering user message, see ApplyUserPromptRequestedPath), otherwise the sanitized provider display name, otherwise a generic "generated-N"; the writer owns MIME/extension correction and collision suffixing, and the part persists the exact final path it returns. A corrected extension additionally surfaces a bounded user-visible notice naming the final path. A prompt-directed path that escapes the workspace (absolute, "..", or "~"-rooted) is redirected into the workspace root under the sanitized basename with a bounded warning.
When no workspace root is available (no provenance anywhere in the parent chain, or a malformed stored value) every item fails with the same per-item warning contract as a write failure — there is deliberately no data-dir fallback, so generated files never land outside the workspace.
A materialization failure drops that one media item, logs the detailed error (including the workspace root) to the debug log only, and emits a runtime [WarningEvent] carrying nothing but safe display metadata — the exact 1-based failed item index and total batch count, the sanitized MIME type, the sanitized provider-supplied name (or FallbackDisplayName when that name is empty, whitespace-only, or missing — never omitted, exactly like the strip_generated_media.go placeholder), and a fixed classified reason from SaveFailureReason (a retry-with-debug hint when the cause is unclassified, never raw error text) — so the failure is observable to the user/caller without leaking the absolute workspace path or a raw OS error (which could contain that path) into a surface a user might paste into a bug report or share screen. Both the name AND the MIME type are provider-supplied, untrusted strings — SanitizeMimeType (shared with strip_generated_media.go's placeholder text) strips control characters and newlines the same way chat.SanitizeDisplayName does for the name, applies the same chat.MaxSanitizedFieldBytes field bound, and falls back to [fallbackMimeType] for empty/invalid input. Every formatted warning/notice is additionally capped at MaxWarningBytes. Only the sanitized MIME type is ever persisted into the resulting chat.Document. One item's failure must not affect a sibling that saves successfully in the same reply, and must not lose the (already generated) accompanying text either.
func (*Service) ResolveGeneratedFile ¶
func (r *Service) ResolveGeneratedFile(ctx context.Context, ref GeneratedFileRef) (*ResolvedGeneratedFile, error)
ResolveGeneratedFile resolves one recorded generated-media reference to its bytes and validated canonical path. It is the only supported read path for generated media: the (owner session, path) pair must have been recorded in the generated-media manifest by materialization, the root kind must match the record, and a workspace path must still be a plain regular file inside the owning session's workspace — a reference alone, however it was forged, never selects a file.
It is safe for concurrent use and intended to be called off the UI update loop (e.g. inside a tea.Cmd).
Source Files