syscall

package
v1.4.0 Latest Latest
Warning

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

 Go to latest Published: Oct 20, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source 
const SyscallABIMajor uint32 = 1

SyscallABIMajor is the major version component of the Syscall ABI.

View Source 
const SyscallABIMinor uint32 = 0

SyscallABIMinor is the minor version component of the Syscall ABI.

View Source 
const SyscallABIPatch uint32 = 0

SyscallABIPatch is the patch version component of the Syscall ABI.

View Source 
const SyscallABIVersion = "1.0.0"

SyscallABIVersion specifies the semantic version of the Fenced Syscall ABI.

Variables

This section is empty.

Functions

This section is empty.

Types

type AttemptIdentity 

type AttemptIdentity struct {
	TenantID     string    `json:"tenant_id"`
	AttemptID    uuid.UUID `json:"attempt_id"`
	FencingToken int64     `json:"fencing_token"`
}

AttemptIdentity binds a syscall invocation to an authenticated attempt lease.

type DispatcherOption 

type DispatcherOption func(*SyscallDispatcher)

DispatcherOption configures the SyscallDispatcher.

func WithAllowedTenant 

func WithAllowedTenant(tenant string) DispatcherOption

WithAllowedTenant sets the tenant boundary for this dispatcher instance.

func WithMetrics 

func WithMetrics(m Metrics) DispatcherOption

WithMetrics attaches a metrics collector to the dispatcher.

func WithNamespaceEnforcer 

func WithNamespaceEnforcer(enforcer *namespace.Enforcer) DispatcherOption

WithNamespaceEnforcer attaches a namespace and quota enforcer to the dispatcher.

func WithRuntimeFence 

func WithRuntimeFence(fences RuntimeFence) DispatcherOption

WithRuntimeFence attaches a fence verifier to the dispatcher.

func WithTracer 

func WithTracer(t trace.Tracer) DispatcherOption

WithTracer attaches an OpenTelemetry tracer to the dispatcher.

type EffectExecutePayload 

type EffectExecutePayload struct {
	AgentID        string          `json:"agent_id"`
	RunID          string          `json:"run_id,omitempty"`
	Provider       string          `json:"provider"`
	Operation      string          `json:"operation"`
	IdempotencyKey string          `json:"idempotency_key"`
	Payload        json.RawMessage `json:"payload,omitempty"`
	Deadline       *time.Time      `json:"deadline,omitempty"`
	TraceID        string          `json:"trace_id,omitempty"`
}

EffectExecutePayload arguments for SYS_EFFECT_EXECUTE.

type EffectGetPayload 

type EffectGetPayload struct {
	EffectID       string `json:"effect_id,omitempty"`
	AgentID        string `json:"agent_id,omitempty"`
	IdempotencyKey string `json:"idempotency_key,omitempty"`
}

EffectGetPayload arguments for SYS_EFFECT_GET.

type EffectInvoker 

type EffectInvoker interface {
	ExecuteEffect(ctx context.Context, req *effect.EffectRequest) (*effect.EffectReceipt, error)
	GetEffect(ctx context.Context, tenantID, effectID string) (*effect.EffectRecord, error)
	GetEffectByIdempotencyKey(ctx context.Context, tenantID, agentID, idempotencyKey string) (*effect.EffectRecord, error)
}

EffectInvoker defines the kernel boundary for external effect execution.

type EffectSyscallHandler 

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

EffectSyscallHandler handles SYS_EFFECT_EXECUTE and SYS_EFFECT_GET.

func NewEffectSyscallHandler 

func NewEffectSyscallHandler(invoker EffectInvoker, caps *capability.Authorizer) *EffectSyscallHandler

NewEffectSyscallHandler creates a new EffectSyscallHandler.

func (*EffectSyscallHandler) Handle 

func (h *EffectSyscallHandler) Handle(ctx *SyscallContext) (json.RawMessage, int64, error)

Handle executes the effect syscall based on SyscallNumber.

type HandlerFunc 

type HandlerFunc func(ctx *SyscallContext) (json.RawMessage, int64, error)

HandlerFunc adapts a function to satisfy the SyscallHandler interface.

func (HandlerFunc) Handle 

func (f HandlerFunc) Handle(ctx *SyscallContext) (json.RawMessage, int64, error)

Handle executes the underlying function.

type IPCAckPayload 

type IPCAckPayload struct {
	AgentVersionRef string   `json:"agent_version_ref"`
	MessageIDs      []string `json:"message_ids"`
}

IPCAckPayload arguments for SYS_IPC_ACK.

type IPCAckResult 

type IPCAckResult struct {
	AcknowledgedIDs []string `json:"acknowledged_ids"`
}

IPCAckResult returned by SYS_IPC_ACK.

type IPCKernelService 

type IPCKernelService interface {
	Send(ctx context.Context, msg *ipc.AgentMessage) error
	Receive(ctx context.Context, addr ipc.AgentAddress, maxMessages int) ([]*ipc.AgentMessage, error)
	Ack(ctx context.Context, addr ipc.AgentAddress, messageIDs []string) error
}

IPCKernelService abstracts the kernel-level IPC communication engine.

type IPCReceivePayload 

type IPCReceivePayload struct {
	AgentVersionRef string `json:"agent_version_ref"`
	MaxMessages     int    `json:"max_messages"`
	WaitMillis      int    `json:"wait_millis"`
}

IPCReceivePayload arguments for SYS_IPC_RECEIVE.

type IPCReceiveResult 

type IPCReceiveResult struct {
	Messages []*ipc.AgentMessage `json:"messages"`
}

IPCReceiveResult returned by SYS_IPC_RECEIVE.

type IPCSendPayload 

type IPCSendPayload struct {
	AgentVersionRef  string           `json:"agent_version_ref"`
	TaskID           uuid.UUID        `json:"task_id"`
	RunID            uuid.UUID        `json:"run_id"`
	To               ipc.AgentAddress `json:"to"`
	Kind             string           `json:"kind"`
	PayloadJSON      json.RawMessage  `json:"payload_json"`
	CorrelationID    string           `json:"correlation_id,omitempty"`
	ReplyToMessageID string           `json:"reply_to_message_id,omitempty"`
	Deadline         *time.Time       `json:"deadline,omitempty"`
}

IPCSendPayload arguments for SYS_IPC_SEND.

type IPCSendResult 

type IPCSendResult struct {
	MessageID  string    `json:"message_id"`
	Replayed   bool      `json:"replayed"`
	AcceptedAt time.Time `json:"accepted_at"`
}

IPCSendResult returned by SYS_IPC_SEND.

type IPCSyscallHandler 

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

IPCSyscallHandler handles SYS_IPC_SEND, SYS_IPC_RECEIVE, and SYS_IPC_ACK.

func NewIPCSyscallHandler 

func NewIPCSyscallHandler(service IPCKernelService) *IPCSyscallHandler

NewIPCSyscallHandler creates a new IPCSyscallHandler.

func (*IPCSyscallHandler) Handle 

func (h *IPCSyscallHandler) Handle(ctx *SyscallContext) (json.RawMessage, int64, error)

Handle executes IPC syscalls.

type MemoryInvoker 

type MemoryInvoker interface {
	Put(context.Context, memory.PutInput) (store.MemoryRecord, bool, error)
	Search(context.Context, memory.SearchInput) ([]store.MemoryRecord, error)
}

MemoryInvoker defines the memory execution boundary.

type MemoryPutPayload 

type MemoryPutPayload struct {
	AgentVersionRef string          `json:"agent_version_ref"`
	Namespace       string          `json:"namespace"`
	Key             string          `json:"key"`
	ContentType     string          `json:"content_type"`
	Content         string          `json:"content"`
	Sensitivity     string          `json:"sensitivity,omitempty"`
	ProvenanceJSON  json.RawMessage `json:"provenance_json,omitempty"`
}

MemoryPutPayload arguments for SYS_MEMORY_PUT.

type MemoryPutResult 

type MemoryPutResult struct {
	Record   store.MemoryRecord `json:"record"`
	Replayed bool               `json:"replayed"`
}

MemoryPutResult returned by SYS_MEMORY_PUT.

type MemorySearchPayload 

type MemorySearchPayload struct {
	AgentVersionRef string `json:"agent_version_ref"`
	Namespace       string `json:"namespace"`
	Query           string `json:"query"`
	Sensitivity     string `json:"sensitivity,omitempty"`
	Limit           int    `json:"limit,omitempty"`
}

MemorySearchPayload arguments for SYS_MEMORY_SEARCH.

type MemorySearchResult 

type MemorySearchResult struct {
	Records []store.MemoryRecord `json:"records"`
}

MemorySearchResult returned by SYS_MEMORY_SEARCH.

type MemorySyscallHandler 

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

MemorySyscallHandler handles SYS_MEMORY_PUT and SYS_MEMORY_SEARCH.

func NewMemorySyscallHandler 

func NewMemorySyscallHandler(invoker MemoryInvoker, caps *capability.Authorizer) *MemorySyscallHandler

NewMemorySyscallHandler creates a new MemorySyscallHandler.

func (*MemorySyscallHandler) Handle 

func (h *MemorySyscallHandler) Handle(ctx *SyscallContext) (json.RawMessage, int64, error)

Handle executes memory syscalls.

type Metrics 

type Metrics interface {
	RecordSyscall(ctx context.Context, syscall SyscallNumber, code SyscallErrorCode, duration time.Duration)
	TotalCount() int64
	SuccessCount() int64
	ErrorCount() int64
}

Metrics defines the interface for collecting syscall metrics.

type ModelBeginPayload 

type ModelBeginPayload struct {
	TaskID          uuid.UUID `json:"task_id"`
	RunID           uuid.UUID `json:"run_id"`
	AgentVersionRef string    `json:"agent_version_ref"`
	ModelRef        string    `json:"model_ref"`
}

ModelBeginPayload arguments for SYS_MODEL_BEGIN.

type ModelBeginResult 

type ModelBeginResult struct {
	CallID          uuid.UUID `json:"call_id"`
	ModelRef        string    `json:"model_ref"`
	Status          string    `json:"status"`
	PriceRevision   string    `json:"price_revision,omitempty"`
	PolicyRevision  string    `json:"policy_revision,omitempty"`
	ResourceVersion int64     `json:"resource_version"`
}

ModelBeginResult returned by SYS_MODEL_BEGIN.

type ModelChatMessage 

type ModelChatMessage struct {
	Role       string              `json:"role"`
	Content    string              `json:"content"`
	ToolCallID string              `json:"tool_call_id,omitempty"`
	ToolCalls  []ModelChatToolCall `json:"tool_calls,omitempty"`
}

ModelChatMessage represents a message turn in conversation.

type ModelChatToolCall 

type ModelChatToolCall struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

ModelChatToolCall represents a tool call requested by an LLM model.

type ModelFinishPayload 

type ModelFinishPayload struct {
	CallID            uuid.UUID `json:"call_id"`
	ExpectedVersion   int64     `json:"expected_version"`
	Status            string    `json:"status"`
	InputTokens       int64     `json:"input_tokens"`
	OutputTokens      int64     `json:"output_tokens"`
	ProviderRequestID string    `json:"provider_request_id,omitempty"`
	FinishReason      string    `json:"finish_reason,omitempty"`
}

ModelFinishPayload arguments for SYS_MODEL_FINISH.

type ModelFinishResult 

type ModelFinishResult struct {
	CallID        uuid.UUID `json:"call_id"`
	ModelRef      string    `json:"model_ref"`
	Status        string    `json:"status"`
	InputTokens   int64     `json:"input_tokens"`
	OutputTokens  int64     `json:"output_tokens"`
	CostUSD       float64   `json:"cost_usd"`
	PriceRevision string    `json:"price_revision,omitempty"`
	FinishReason  string    `json:"finish_reason,omitempty"`
}

ModelFinishResult returned by SYS_MODEL_FINISH.

type ModelInvokePayload 

type ModelInvokePayload struct {
	TaskID          uuid.UUID          `json:"task_id"`
	RunID           uuid.UUID          `json:"run_id"`
	AgentVersionRef string             `json:"agent_version_ref"`
	ModelRef        string             `json:"model_ref"`
	Messages        []ModelChatMessage `json:"messages"`
	Stream          bool               `json:"stream,omitempty"`
	Temperature     *float64           `json:"temperature,omitempty"`
	MaxOutputTokens int32              `json:"max_output_tokens,omitempty"`
	Tools           []ModelToolDef     `json:"tools,omitempty"`
}

ModelInvokePayload arguments for SYS_MODEL_INVOKE.

type ModelInvokeResult 

type ModelInvokeResult struct {
	CallID            uuid.UUID           `json:"call_id"`
	ModelRef          string              `json:"model_ref"`
	Status            string              `json:"status"`
	Content           string              `json:"content,omitempty"`
	InputTokens       int64               `json:"input_tokens"`
	OutputTokens      int64               `json:"output_tokens"`
	CostUSD           float64             `json:"cost_usd"`
	PriceRevision     string              `json:"price_revision,omitempty"`
	FinishReason      string              `json:"finish_reason,omitempty"`
	ProviderRequestID string              `json:"provider_request_id,omitempty"`
	ToolCalls         []ModelChatToolCall `json:"tool_calls,omitempty"`
}

ModelInvokeResult returned by SYS_MODEL_INVOKE.

type ModelInvoker 

type ModelInvoker interface {
	Begin(context.Context, model.BeginInput) (model.BeginResult, error)
	GetModelCall(context.Context, string, uuid.UUID) (store.ModelCall, error)
	Settle(context.Context, store.ModelCall, int64, model.Usage) error
	Finish(context.Context, store.ModelCall, model.FinishInput) (store.ModelCall, error)
}

ModelInvoker governs the begin/settle/finish model session lifecycle.

type ModelRunner 

type ModelRunner interface {
	InvokeStream(context.Context, model.InvokeInput, func(string)) (model.InvokeOutput, error)
}

ModelRunner executes real model invocations.

type ModelSettlePayload 

type ModelSettlePayload struct {
	CallID       uuid.UUID `json:"call_id"`
	Sequence     int64     `json:"sequence"`
	InputTokens  int64     `json:"input_tokens"`
	OutputTokens int64     `json:"output_tokens"`
}

ModelSettlePayload arguments for SYS_MODEL_SETTLE.

type ModelSettleResult 

type ModelSettleResult struct {
	CallID uuid.UUID `json:"call_id"`
}

ModelSettleResult returned by SYS_MODEL_SETTLE.

type ModelSyscallHandler 

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

ModelSyscallHandler handles SYS_MODEL_INVOKE, SYS_MODEL_BEGIN, SYS_MODEL_SETTLE, SYS_MODEL_FINISH.

func NewModelSyscallHandler 

func NewModelSyscallHandler(runner ModelRunner, invoker ModelInvoker, caps *capability.Authorizer) *ModelSyscallHandler

NewModelSyscallHandler creates a new ModelSyscallHandler.

func (*ModelSyscallHandler) Handle 

func (h *ModelSyscallHandler) Handle(ctx *SyscallContext) (json.RawMessage, int64, error)

Handle executes model syscalls.

type ModelToolDef 

type ModelToolDef struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Parameters  json.RawMessage `json:"parameters"`
}

ModelToolDef defines a callable tool presented to the model.

type NamespaceGetPayload 

type NamespaceGetPayload struct {
	Namespace string `json:"namespace"`
}

NamespaceGetPayload arguments for SYS_NAMESPACE_GET.

type NamespaceInfo 

type NamespaceInfo struct {
	TenantID    string                   `json:"tenant_id"`
	Name        string                   `json:"name"`
	DisplayName string                   `json:"display_name,omitempty"`
	Description string                   `json:"description,omitempty"`
	Phase       namespace.NamespacePhase `json:"phase"`
	Labels      map[string]string        `json:"labels,omitempty"`
	Quota       namespace.ResourceQuota  `json:"quota"`
	CreatedAt   time.Time                `json:"created_at"`
	UpdatedAt   time.Time                `json:"updated_at"`
}

NamespaceInfo returned by SYS_NAMESPACE_GET.

type ResourceQuotaInfo 

type ResourceQuotaInfo struct {
	TenantID  string                  `json:"tenant_id"`
	Namespace string                  `json:"namespace"`
	Quota     namespace.ResourceQuota `json:"quota"`
}

ResourceQuotaInfo returned by SYS_RESOURCE_QUOTA_GET.

type ResourceQuotaPayload 

type ResourceQuotaPayload struct {
	Namespace string `json:"namespace"`
}

ResourceQuotaPayload arguments for SYS_RESOURCE_QUOTA_GET.

type ResourceSyscallHandler 

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

ResourceSyscallHandler handles Resource and Namespace syscalls: SysNamespaceGet (701), SysResourceQuotaGet (702), SysResourceUsageGet (703).

func NewResourceSyscallHandler 

func NewResourceSyscallHandler(store namespace.Store) *ResourceSyscallHandler

NewResourceSyscallHandler creates a new ResourceSyscallHandler.

func (*ResourceSyscallHandler) Handle 

func (h *ResourceSyscallHandler) Handle(ctx *SyscallContext) (json.RawMessage, int64, error)

Handle executes resource/namespace system calls.

type ResourceUsageInfo 

type ResourceUsageInfo struct {
	Usage namespace.ResourceUsage `json:"usage"`
}

ResourceUsageInfo returned by SYS_RESOURCE_USAGE_GET.

type ResourceUsagePayload 

type ResourceUsagePayload struct {
	Namespace string `json:"namespace"`
}

ResourceUsagePayload arguments for SYS_RESOURCE_USAGE_GET.

type RuntimeCheckpointPayload 

type RuntimeCheckpointPayload struct {
	ExpectedAttemptVersion int64                   `json:"expected_attempt_version"`
	CheckpointID           string                  `json:"checkpoint_id"`
	State                  store.ArtifactReference `json:"state"`
	ConfirmedReceiptIDs    []string                `json:"confirmed_receipt_ids,omitempty"`
}

RuntimeCheckpointPayload arguments for SYS_RUNTIME_CHECKPOINT.

type RuntimeCheckpointResult 

type RuntimeCheckpointResult struct {
	Checkpoint     store.Checkpoint `json:"checkpoint"`
	AttemptVersion int64            `json:"attempt_version"`
}

RuntimeCheckpointResult returned by SYS_RUNTIME_CHECKPOINT.

type RuntimeCompletePayload 

type RuntimeCompletePayload struct {
	ExpectedAttemptVersion int64                   `json:"expected_attempt_version"`
	Result                 store.ArtifactReference `json:"result"`
}

RuntimeCompletePayload arguments for SYS_RUNTIME_COMPLETE.

type RuntimeCompleteResult 

type RuntimeCompleteResult struct {
	AttemptVersion int64  `json:"attempt_version"`
	ResultRef      string `json:"result_ref"`
}

RuntimeCompleteResult returned by SYS_RUNTIME_COMPLETE.

type RuntimeFence 

type RuntimeFence interface {
	GetRuntimeAssignment(ctx context.Context, tenantID string, attemptID uuid.UUID, fencingToken int64) (store.RuntimeAssignment, error)
}

RuntimeFence validates that an attempt's fencing token is current.

type RuntimeLifecycleInvoker 

type RuntimeLifecycleInvoker interface {
	CommitCheckpoint(context.Context, store.CommitCheckpointInput) (store.Checkpoint, store.Attempt, error)
	CompleteAttempt(context.Context, store.CompleteAttemptInput) (store.CompleteAttemptResult, error)
}

RuntimeLifecycleInvoker defines the execution boundary for runtime attempts and checkpoints.

type RuntimeSyscallHandler 

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

RuntimeSyscallHandler handles SYS_RUNTIME_CHECKPOINT, SYS_RUNTIME_COMPLETE, and SYS_RUNTIME_YIELD.

func NewRuntimeSyscallHandler 

func NewRuntimeSyscallHandler(invoker RuntimeLifecycleInvoker) *RuntimeSyscallHandler

NewRuntimeSyscallHandler creates a new RuntimeSyscallHandler.

func (*RuntimeSyscallHandler) Handle 

func (h *RuntimeSyscallHandler) Handle(ctx *SyscallContext) (json.RawMessage, int64, error)

Handle executes runtime lifecycle syscalls.

type RuntimeYieldPayload 

type RuntimeYieldPayload struct {
	Reason string `json:"reason,omitempty"`
}

RuntimeYieldPayload arguments for SYS_RUNTIME_YIELD.

type RuntimeYieldResult 

type RuntimeYieldResult struct {
	Yielded bool `json:"yielded"`
}

RuntimeYieldResult returned by SYS_RUNTIME_YIELD.

type ServiceHeartbeatPayload 

type ServiceHeartbeatPayload struct {
	ServiceID  uuid.UUID `json:"service_id"`
	InstanceID string    `json:"instance_id"`
	Status     string    `json:"status"`
	LoadScore  float64   `json:"load_score,omitempty"`
}

ServiceHeartbeatPayload arguments for SYS_SERVICE_HEARTBEAT.

type ServiceHeartbeatResult 

type ServiceHeartbeatResult struct {
	Acknowledged       bool `json:"acknowledged"`
	RebalanceRequested bool `json:"rebalance_requested"`
}

ServiceHeartbeatResult returned by SYS_SERVICE_HEARTBEAT.

type ServiceQueryPayload 

type ServiceQueryPayload struct {
	Name      string `json:"name,omitempty"`
	Namespace string `json:"namespace,omitempty"`
}

ServiceQueryPayload arguments for SYS_SERVICE_QUERY.

type ServiceQueryResult 

type ServiceQueryResult struct {
	Services []*supervisor.Service `json:"services"`
}

ServiceQueryResult returned by SYS_SERVICE_QUERY.

type ServiceSyscallHandler 

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

ServiceSyscallHandler handles SYS_SERVICE_HEARTBEAT and SYS_SERVICE_QUERY.

func NewServiceSyscallHandler 

func NewServiceSyscallHandler(store supervisor.Store) *ServiceSyscallHandler

NewServiceSyscallHandler creates a new ServiceSyscallHandler.

func (*ServiceSyscallHandler) Handle 

func (h *ServiceSyscallHandler) Handle(ctx *SyscallContext) (json.RawMessage, int64, error)

Handle executes supervisor service syscalls.

type StandardMetrics 

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

StandardMetrics collects Prometheus/OpenTelemetry metrics and in-memory counters.

func NewStandardMetrics 

func NewStandardMetrics() *StandardMetrics

NewStandardMetrics initializes OpenTelemetry instruments and atomic counters.

func (*StandardMetrics) ErrorCount 

func (m *StandardMetrics) ErrorCount() int64

ErrorCount returns number of failed syscall invocations.

func (*StandardMetrics) RecordSyscall 

func (m *StandardMetrics) RecordSyscall(ctx context.Context, syscall SyscallNumber, code SyscallErrorCode, duration time.Duration)

RecordSyscall records the execution of a system call.

func (*StandardMetrics) SuccessCount 

func (m *StandardMetrics) SuccessCount() int64

SuccessCount returns number of successful syscall invocations.

func (*StandardMetrics) TotalCount 

func (m *StandardMetrics) TotalCount() int64

TotalCount returns total number of syscall invocations recorded.

type SyscallClient 

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

SyscallClient is the unified client interface for executing kernel system calls.

func NewClient 

func NewClient(invoker SyscallInvoker) *SyscallClient

NewClient creates a new SyscallClient.

func (*SyscallClient) ABIVersion 

func (c *SyscallClient) ABIVersion() string

ABIVersion returns the Syscall ABI semantic version supported by this client.

func (*SyscallClient) AckIPC 

func (c *SyscallClient) AckIPC(ctx context.Context, id AttemptIdentity, payload IPCAckPayload) (IPCAckResult, error)

AckIPC calls SYS_IPC_ACK.

func (*SyscallClient) BeginModel 

func (c *SyscallClient) BeginModel(ctx context.Context, id AttemptIdentity, payload ModelBeginPayload) (ModelBeginResult, int64, error)

BeginModel calls SYS_MODEL_BEGIN.

func (*SyscallClient) Call 

func (c *SyscallClient) Call(ctx context.Context, syscall SyscallNumber, identity AttemptIdentity, payload any) (json.RawMessage, int64, error)

Call executes an arbitrary system call with payload and returns the raw result and resource version.

func (*SyscallClient) Checkpoint 

func (c *SyscallClient) Checkpoint(ctx context.Context, id AttemptIdentity, payload RuntimeCheckpointPayload) (RuntimeCheckpointResult, int64, error)

Checkpoint calls SYS_RUNTIME_CHECKPOINT.

func (*SyscallClient) Complete 

func (c *SyscallClient) Complete(ctx context.Context, id AttemptIdentity, payload RuntimeCompletePayload) (RuntimeCompleteResult, int64, error)

Complete calls SYS_RUNTIME_COMPLETE.

func (*SyscallClient) ExecuteEffect 

func (c *SyscallClient) ExecuteEffect(ctx context.Context, id AttemptIdentity, payload EffectExecutePayload) (effect.EffectReceipt, int64, error)

ExecuteEffect calls SYS_EFFECT_EXECUTE.

func (*SyscallClient) FinishModel 

func (c *SyscallClient) FinishModel(ctx context.Context, id AttemptIdentity, payload ModelFinishPayload) (ModelFinishResult, int64, error)

FinishModel calls SYS_MODEL_FINISH.

func (*SyscallClient) GetEffect 

func (c *SyscallClient) GetEffect(ctx context.Context, id AttemptIdentity, payload EffectGetPayload) (effect.EffectRecord, int64, error)

GetEffect calls SYS_EFFECT_GET.

func (*SyscallClient) GetNamespace 

func (c *SyscallClient) GetNamespace(ctx context.Context, id AttemptIdentity, payload NamespaceGetPayload) (NamespaceInfo, error)

GetNamespace calls SYS_NAMESPACE_GET.

func (*SyscallClient) GetResourceQuota 

func (c *SyscallClient) GetResourceQuota(ctx context.Context, id AttemptIdentity, payload ResourceQuotaPayload) (ResourceQuotaInfo, error)

GetResourceQuota calls SYS_RESOURCE_QUOTA_GET.

func (*SyscallClient) GetResourceUsage 

func (c *SyscallClient) GetResourceUsage(ctx context.Context, id AttemptIdentity, payload ResourceUsagePayload) (ResourceUsageInfo, error)

GetResourceUsage calls SYS_RESOURCE_USAGE_GET.

func (*SyscallClient) HeartbeatService 

func (c *SyscallClient) HeartbeatService(ctx context.Context, id AttemptIdentity, payload ServiceHeartbeatPayload) (ServiceHeartbeatResult, error)

HeartbeatService calls SYS_SERVICE_HEARTBEAT.

func (*SyscallClient) InvokeModel 

func (c *SyscallClient) InvokeModel(ctx context.Context, id AttemptIdentity, payload ModelInvokePayload) (ModelInvokeResult, error)

InvokeModel calls SYS_MODEL_INVOKE.

func (*SyscallClient) InvokeTool 

func (c *SyscallClient) InvokeTool(ctx context.Context, id AttemptIdentity, payload ToolInvokePayload) (ToolInvokeResult, error)

InvokeTool calls SYS_TOOL_INVOKE.

func (*SyscallClient) ListTools 

func (c *SyscallClient) ListTools(ctx context.Context, id AttemptIdentity, payload ToolListPayload) (ToolListResult, error)

ListTools calls SYS_TOOL_LIST.

func (*SyscallClient) PutMemory 

func (c *SyscallClient) PutMemory(ctx context.Context, id AttemptIdentity, payload MemoryPutPayload) (MemoryPutResult, int64, error)

PutMemory calls SYS_MEMORY_PUT.

func (*SyscallClient) QueryServices 

func (c *SyscallClient) QueryServices(ctx context.Context, id AttemptIdentity, payload ServiceQueryPayload) (ServiceQueryResult, error)

QueryServices calls SYS_SERVICE_QUERY.

func (*SyscallClient) ReceiveIPC 

func (c *SyscallClient) ReceiveIPC(ctx context.Context, id AttemptIdentity, payload IPCReceivePayload) (IPCReceiveResult, error)

ReceiveIPC calls SYS_IPC_RECEIVE.

func (*SyscallClient) SearchMemory 

func (c *SyscallClient) SearchMemory(ctx context.Context, id AttemptIdentity, payload MemorySearchPayload) (MemorySearchResult, error)

SearchMemory calls SYS_MEMORY_SEARCH.

func (*SyscallClient) SendIPC 

func (c *SyscallClient) SendIPC(ctx context.Context, id AttemptIdentity, payload IPCSendPayload) (IPCSendResult, error)

SendIPC calls SYS_IPC_SEND.

func (*SyscallClient) SettleModel 

func (c *SyscallClient) SettleModel(ctx context.Context, id AttemptIdentity, payload ModelSettlePayload) (ModelSettleResult, error)

SettleModel calls SYS_MODEL_SETTLE.

func (*SyscallClient) Yield 

func (c *SyscallClient) Yield(ctx context.Context, id AttemptIdentity, payload RuntimeYieldPayload) (RuntimeYieldResult, error)

Yield calls SYS_RUNTIME_YIELD.

type SyscallContext 

type SyscallContext struct {
	context.Context
	Request    SyscallRequest
	Assignment store.RuntimeAssignment
}

SyscallContext encapsulates execution context, request payload, and verified attempt assignment.

type SyscallDescriptor 

type SyscallDescriptor struct {
	Number       SyscallNumber
	Name         string
	Category     string
	IsReadOnly   bool
	Description  string
	SinceVersion string
}

SyscallDescriptor describes metadata and execution properties of a system call.

func AllDescriptors 

func AllDescriptors() []SyscallDescriptor

AllDescriptors returns a slice of all known syscall descriptors.

type SyscallDispatcher 

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

SyscallDispatcher is the central kernel execution engine for all agent system calls.

func NewDispatcher 

func NewDispatcher(opts ...DispatcherOption) *SyscallDispatcher

NewDispatcher creates a new SyscallDispatcher.

func (*SyscallDispatcher) Dispatch 

func (d *SyscallDispatcher) Dispatch(ctx context.Context, req SyscallRequest) SyscallResponse

Dispatch processes and executes a system call request through security fences and registered handlers.

func (*SyscallDispatcher) GetHandler 

func (d *SyscallDispatcher) GetHandler(number SyscallNumber) (SyscallHandler, bool)

GetHandler retrieves the registered handler for a syscall number.

func (*SyscallDispatcher) Register 

func (d *SyscallDispatcher) Register(number SyscallNumber, handler SyscallHandler)

Register registers a handler for a given syscall number.

func (*SyscallDispatcher) RegisterFunc 

func (d *SyscallDispatcher) RegisterFunc(number SyscallNumber, fn func(ctx *SyscallContext) (json.RawMessage, int64, error))

RegisterFunc registers a handler function for a given syscall number.

type SyscallError 

type SyscallError struct {
	Code    SyscallErrorCode
	Message string
	Cause   error
}

SyscallError represents a strongly-typed kernel error encountered during a system call.

func NewSyscallError 

func NewSyscallError(code SyscallErrorCode, msg string) *SyscallError

NewSyscallError creates a new SyscallError with code and formatted message.

func WrapError 

func WrapError(code SyscallErrorCode, msg string, cause error) *SyscallError

WrapError wraps an existing error with a SyscallErrorCode.

func (*SyscallError) Error 

func (e *SyscallError) Error() string

Error implements the standard error interface.

func (*SyscallError) Unwrap 

func (e *SyscallError) Unwrap() error

Unwrap returns the underlying cause of the error.

type SyscallErrorCode 

type SyscallErrorCode int32

SyscallErrorCode represents a POSIX-like kernel error number returned by system calls. 

const (
	// SyscallOK indicates normal successful completion.
	SyscallOK SyscallErrorCode = 0

	// SyscallEPERM indicates operation not permitted (capability denied, tenant mismatch).
	SyscallEPERM SyscallErrorCode = 1

	// SyscallENOENT indicates no such file, directory, entity, or tool.
	SyscallENOENT SyscallErrorCode = 2

	// SyscallEINVAL indicates invalid argument, malformed payload, or missing fields.
	SyscallEINVAL SyscallErrorCode = 3

	// SyscallEBUSY indicates resource or attempt is currently locked or in a conflicting state.
	SyscallEBUSY SyscallErrorCode = 4

	// SyscallETIMEDOUT indicates connection or operation deadline exceeded.
	SyscallETIMEDOUT SyscallErrorCode = 5

	// SyscallENOMEM indicates memory, token quota, or financial budget exceeded.
	SyscallENOMEM SyscallErrorCode = 6

	// SyscallEFENCE indicates stale fencing token or invalid attempt lease.
	SyscallEFENCE SyscallErrorCode = 7

	// SyscallENOSYS indicates function/system call not implemented or unknown.
	SyscallENOSYS SyscallErrorCode = 8

	// SyscallEINTERNAL indicates an unexpected internal kernel error.
	SyscallEINTERNAL SyscallErrorCode = 9

	// SyscallEUNKNOWN indicates an ambiguous external side-effect outcome; auto-replay forbidden.
	SyscallEUNKNOWN SyscallErrorCode = 10
)

func ErrorToCode 

func ErrorToCode(err error) (SyscallErrorCode, string)

ErrorToCode inspects an error and maps it to a canonical SyscallErrorCode and message.

func (SyscallErrorCode) StandardName 

func (c SyscallErrorCode) StandardName() string

StandardName returns the short POSIX-style name (e.g. "EPERM", "EINVAL").

func (SyscallErrorCode) String 

func (c SyscallErrorCode) String() string

String returns a human-readable representation of the error code.

type SyscallHandler 

type SyscallHandler interface {
	Handle(ctx *SyscallContext) (json.RawMessage, int64, error)
}

SyscallHandler handles execution of a specific system call.

type SyscallInvoker 

type SyscallInvoker interface {
	Dispatch(ctx context.Context, req SyscallRequest) SyscallResponse
}

SyscallInvoker executes a system call request and returns the system call response.

type SyscallNumber 

type SyscallNumber uint32

SyscallNumber represents a unique kernel-level system call identifier. 

const (
	// SyscallNone represents an uninitialized or unknown system call.
	SyscallNone SyscallNumber = 0

	// Tool Subsystem (100 - 199)
	SysToolInvoke SyscallNumber = 101
	SysToolList   SyscallNumber = 102

	// Model Subsystem (200 - 299)
	SysModelInvoke SyscallNumber = 201
	SysModelBegin  SyscallNumber = 202
	SysModelSettle SyscallNumber = 203
	SysModelFinish SyscallNumber = 204

	// Memory Subsystem (300 - 399)
	SysMemoryPut    SyscallNumber = 301
	SysMemorySearch SyscallNumber = 302

	// IPC Subsystem (400 - 499)
	SysIPCSend    SyscallNumber = 401
	SysIPCReceive SyscallNumber = 402
	SysIPCAck     SyscallNumber = 403

	// Runtime Subsystem (500 - 599)
	SysRuntimeCheckpoint SyscallNumber = 501
	SysRuntimeComplete   SyscallNumber = 502
	SysRuntimeYield      SyscallNumber = 503

	// Service / Supervisor Subsystem (600 - 699)
	SysServiceHeartbeat SyscallNumber = 601
	SysServiceQuery     SyscallNumber = 602

	// Resource / Namespace Subsystem (700 - 799)
	SysNamespaceGet     SyscallNumber = 701
	SysResourceQuotaGet SyscallNumber = 702
	SysResourceUsageGet SyscallNumber = 703

	// Effect Subsystem (800 - 899)
	SysEffectExecute SyscallNumber = 801
	SysEffectGet     SyscallNumber = 802
)

func ParseSyscallNumber 

func ParseSyscallNumber(str string) (SyscallNumber, error)

ParseSyscallNumber parses a string (either uppercase symbolic name, lowercase name, or integer) into a SyscallNumber.

func (SyscallNumber) Category 

func (s SyscallNumber) Category() string

Category returns the subsystem category of the syscall (e.g. "tool", "model", "ipc").

func (SyscallNumber) Descriptor 

func (s SyscallNumber) Descriptor() (SyscallDescriptor, bool)

Descriptor returns the full metadata descriptor for this syscall.

func (SyscallNumber) IsReadOnly 

func (s SyscallNumber) IsReadOnly() bool

IsReadOnly returns true if the syscall does not mutate kernel or domain state.

func (SyscallNumber) Name 

func (s SyscallNumber) Name() string

Name returns the canonical lowercase syscall name (e.g. "sys_tool_invoke").

func (SyscallNumber) String 

func (s SyscallNumber) String() string

String returns the uppercase symbolic name of the syscall.

type SyscallRequest 

type SyscallRequest struct {
	Syscall        SyscallNumber     `json:"syscall"`
	Identity       AttemptIdentity   `json:"identity"`
	PayloadJSON    json.RawMessage   `json:"payload_json"`
	IdempotencyKey string            `json:"idempotency_key,omitempty"`
	Metadata       map[string]string `json:"metadata,omitempty"`
}

SyscallRequest is the canonical system call execution envelope.

type SyscallResponse 

type SyscallResponse struct {
	Syscall         SyscallNumber    `json:"syscall"`
	ErrorCode       SyscallErrorCode `json:"error_code"`
	ErrorMessage    string           `json:"error_message,omitempty"`
	ResultJSON      json.RawMessage  `json:"result_json,omitempty"`
	DurationUS      int64            `json:"duration_us"`
	ResourceVersion int64            `json:"resource_version,omitempty"`
}

SyscallResponse is the canonical system call return envelope.

func (SyscallResponse) IsSuccess 

func (r SyscallResponse) IsSuccess() bool

IsSuccess returns true if the syscall completed without error.

type ToolInvokePayload 

type ToolInvokePayload struct {
	TaskID          uuid.UUID       `json:"task_id"`
	RunID           uuid.UUID       `json:"run_id"`
	AgentVersionRef string          `json:"agent_version_ref"`
	ToolName        string          `json:"tool_name"`
	ToolVersion     string          `json:"tool_version"`
	Action          string          `json:"action"`
	Resource        string          `json:"resource"`
	ArgsJSON        json.RawMessage `json:"args_json"`
	ApprovalID      string          `json:"approval_id,omitempty"`
	SecretRef       string          `json:"secret_ref,omitempty"`
}

ToolInvokePayload arguments for SYS_TOOL_INVOKE.

type ToolInvokeResult 

type ToolInvokeResult struct {
	Outcome          string          `json:"outcome"`
	ResultJSON       json.RawMessage `json:"result_json,omitempty"`
	ApprovalID       string          `json:"approval_id,omitempty"`
	DenyReasons      []string        `json:"deny_reasons,omitempty"`
	PolicyRevision   string          `json:"policy_revision,omitempty"`
	ReceiptOperation string          `json:"receipt_operation,omitempty"`
	ToolCallID       string          `json:"tool_call_id,omitempty"`
}

ToolInvokeResult returned by SYS_TOOL_INVOKE.

type ToolInvoker 

type ToolInvoker interface {
	InvokeTool(context.Context, tool.InvokeInput) (tool.InvokeResult, error)
	ListTools(context.Context, string) ([]store.ToolDescriptor, error)
	GetToolDescriptor(ctx context.Context, tenantID, name, version string) (store.ToolDescriptor, error)
}

ToolInvoker defines the kernel tool execution boundary.

type ToolListPayload 

type ToolListPayload struct {
	AgentVersionRef string `json:"agent_version_ref"`
}

ToolListPayload arguments for SYS_TOOL_LIST.

type ToolListResult 

type ToolListResult struct {
	Tools []store.ToolDescriptor `json:"tools"`
}

ToolListResult returned by SYS_TOOL_LIST.

type ToolSyscallHandler 

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

ToolSyscallHandler handles SYS_TOOL_INVOKE and SYS_TOOL_LIST.

func NewToolSyscallHandler 

func NewToolSyscallHandler(invoker ToolInvoker, caps *capability.Authorizer) *ToolSyscallHandler

NewToolSyscallHandler creates a new ToolSyscallHandler.

func (*ToolSyscallHandler) Handle 

func (h *ToolSyscallHandler) Handle(ctx *SyscallContext) (json.RawMessage, int64, error)

Handle executes the tool syscall according to the request's SyscallNumber.

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.