Documentation
¶
Overview ¶
Package assistant is the SingerOS business wrapper layer for agent runs.
Service is the single business entry point for an Agent Run:
validate → run.started → Preparer → agent.Executor → Finalizer → terminal → post-run
It owns the business RunRequest/RunResult, wires Preparer and Finalizer via ports, and delegates execution to the agent.Executor.
Index ¶
- func Adapt(legacy tools.Tool, toolCtx tools.ToolContext) agent.Tool
- type ArtifactBaseline
- type ArtifactPayload
- type AttachmentIngestor
- type Finalization
- type Finalizer
- type Journal
- type JournalEventRecord
- type JournalFactory
- type JournalSnapshot
- type PreparedRun
- type Preparer
- type Service
- type ToolProvider
- type WorkspaceManager
- type WorkspacePreparation
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type ArtifactBaseline ¶
type ArtifactBaseline struct {
Ref string
}
ArtifactBaseline captures artifact state before execution.
type ArtifactPayload ¶
type ArtifactPayload struct {
ArtifactID string `json:"artifact_id,omitempty"`
Title string `json:"title,omitempty"`
Filename string `json:"filename,omitempty"`
OriginalName string `json:"original_name,omitempty"`
Description string `json:"description,omitempty"`
MimeType string `json:"mime_type,omitempty"`
ArtifactType string `json:"artifact_type,omitempty"`
FileSize int64 `json:"file_size,omitempty"`
RelativePath string `json:"relative_path,omitempty"`
StorageKey string `json:"storage_key,omitempty"`
StorageURI string `json:"storage_uri,omitempty"`
Sha256 string `json:"sha256,omitempty"`
Source string `json:"source,omitempty"`
Status string `json:"status,omitempty"`
}
ArtifactPayload is a local copy to avoid depending on the events package.
type AttachmentIngestor ¶
type AttachmentIngestor interface {
IngestAttachments(ctx context.Context, req *assistantdomain.RunRequest)
}
AttachmentIngestor downloads and commits user attachments into the workspace. It is best-effort: failures are logged but do not block the run.
func NewAttachmentIngestor ¶
func NewAttachmentIngestor() AttachmentIngestor
NewAttachmentIngestor creates a new AttachmentIngestor.
type Finalization ¶
type Finalization struct {
Result *assistantdomain.RunResult
Events []*agent.Event
}
Finalization holds the final business result and events emitted before terminal.
type Finalizer ¶
type Finalizer interface {
FinalizeRequired(
ctx context.Context,
run *PreparedRun,
runtimeResult *agent.ExecutionResult,
snapshot JournalSnapshot,
) (*Finalization, error)
PostRunBestEffort(
ctx context.Context,
run *PreparedRun,
result *assistantdomain.RunResult,
snapshot JournalSnapshot,
)
}
Finalizer performs required business finalization and best-effort post-run work.
type Journal ¶
type Journal interface {
Record(ctx context.Context, event *agent.Event) error
Snapshot() JournalSnapshot
}
Journal records, sequences, archives, and forwards events for one business run.
func NewJournal ¶
func NewJournal(req *assistantdomain.RunRequest, sink agent.EventSink) Journal
NewJournal creates a Journal bound to a request and downstream sink.
type JournalEventRecord ¶
type JournalEventRecord struct {
Seq int64 `json:"seq"`
LastSeq int64 `json:"last_seq,omitempty"`
Type agent.EventType `json:"type"`
Timestamp int64 `json:"timestamp"`
Payload json.RawMessage `json:"payload,omitempty"`
}
JournalEventRecord is an archived non-terminal event.
type JournalFactory ¶
type JournalFactory interface {
New(req *assistantdomain.RunRequest, sink agent.EventSink) Journal
}
JournalFactory creates a Journal bound to a run and downstream sink.
func NewJournalFactory ¶
func NewJournalFactory() JournalFactory
NewJournalFactory creates the default assistant JournalFactory.
type JournalSnapshot ¶
type JournalSnapshot struct {
ToolCalls []agent.ToolCallRecord
Usage *agent.Usage
MessageCount int
ToolFailures int
ToolNames []string
Events []JournalEventRecord
}
JournalSnapshot is the immutable activity summary used by finalization.
type PreparedRun ¶
type PreparedRun struct {
Request *assistantdomain.RunRequest
Execution agent.ExecutionRequest
Workspace WorkspacePreparation
Baseline ArtifactBaseline
}
PreparedRun binds the immutable business snapshot to its pure execution request.
type Preparer ¶
type Preparer interface {
Prepare(ctx context.Context, req *assistantdomain.RunRequest) (*PreparedRun, error)
}
Preparer converts a business run request into an immutable prepared run.
func NewPreparer ¶
func NewPreparer(builder *lifecyclecontext.ContextBuilder) Preparer
NewPreparer creates a new RunPreparer.
func NewPreparerWithPorts ¶
func NewPreparerWithPorts( builder *lifecyclecontext.ContextBuilder, wm WorkspaceManager, ai AttachmentIngestor, modelStore *modelrouter.ModelStore, ) Preparer
NewPreparerWithPorts creates a RunPreparer with injected workspace and attachment ports.
func NewPreparerWithTools ¶
func NewPreparerWithTools( builder *lifecyclecontext.ContextBuilder, wm WorkspaceManager, ai AttachmentIngestor, modelStore *modelrouter.ModelStore, toolProvider ToolProvider, ) Preparer
NewPreparerWithTools creates a RunPreparer with all external dependencies injected.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the single business entry point for an Agent Run.
func NewService ¶
func NewService( preparer Preparer, executor *agent.Executor, finalizer Finalizer, journal JournalFactory, ) *Service
NewService creates a new assistant Service.
func (*Service) Run ¶
func (s *Service) Run( ctx context.Context, req *assistantdomain.RunRequest, sink agent.EventSink, ) (*assistantdomain.RunResult, error)
Run executes one business agent run. It:
- Validates the request
- Emits run.started
- Calls Preparer to build ExecutionRequest
- Calls agent.Executor for the runtime lifecycle
- Calls Finalizer for required post-run tasks
- Emits artifact events
- Emits exactly one terminal event
- Runs best-effort post-run tasks
type ToolProvider ¶
type ToolProvider interface {
ToolsFor(
req *assistantdomain.RunRequest,
workspace WorkspacePreparation,
) ([]agent.Tool, error)
}
ToolProvider resolves business tools into the neutral execution contract.
func NewToolProvider ¶
func NewToolProvider(registry *tools.Registry) ToolProvider
NewToolProvider adapts the application tool registry at the assistant boundary.
type WorkspaceManager ¶
type WorkspaceManager interface {
PrepareWorkspace(ctx context.Context, req *assistantdomain.RunRequest) (WorkspacePreparation, error)
}
WorkspaceManager prepares task workspaces (clone/populate repo).
func NewWorkspaceManager ¶
func NewWorkspaceManager(env, giteaEndpoint, giteaOwner, giteaAccessToken string) WorkspaceManager
NewWorkspaceManager creates a WorkspaceManager backed by the given Gitea config.
Source Files
Directories