pkg/

directory
v1.0.8 Latest Latest
Warning

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

 Go to latest Published: Aug 13, 2026 License: GPL-3.0

README

AgentX Go packages

Every directory below pkg/ is importable by other Go modules on the supported Unix and Windows build targets. This makes the implemented runtime available for composition and testing without the Go internal import restriction. Unsupported operating systems may expose portable leaf packages, but the complete application does not claim to build there.

Importability is not a promise that every exported identifier is a stable, untrusted-client SDK. These packages currently expose the runtime's trusted-host composition surface; compatibility follows the runtime conformance profile, and APIs may still evolve with those contracts.

Callers must preserve the same authority boundaries as the root application:

  • Validate untrusted wire and stored data with the owning package before use.
  • Route model-requested effects through tool validation, permission, sandbox, hook, and result-normalization contracts; public visibility is never authorization.
  • Do not derive trust, policy bypass, protected paths, provider credentials, or executable extension configuration directly from untrusted input.
  • Treat configuration, MCP environments, transcripts, task output, and diagnostic data as potentially sensitive. Do not reflect, log, or serialize credentials; config.Azure.APIKey is deliberately excluded from JSON.
  • Use config.LoadProviderRegistry or config.LoadProviderRegistryAtRoot for trusted-host preselection of provider profiles. Their descriptors omit Azure routing and credentials, but callers must still apply the returned complete CredentialSanitizer to the fully framed output. Use config.Load only when selecting and constructing one model-backed runtime profile.
  • Do not confuse ProviderRegistry.MarshalJSON with the external discovery wire protocol. The package-native projection has no top-level protocol version and emits ProviderDescriptor fields such as type and reasoning.default_effort; it is useful only inside a trusted Go composition that preserves the sanitizer boundary. External tools and editor hosts use agentx --list-providers --output-format json, whose standalone public schema is version 1 and whose closed descriptors use compatibility fields such as providerType, supportedReasoningEfforts, and reasoning.defaultEffort. Neither projection contains literal endpoint URLs.
  • Hold the documented session lock while mutating durable session state, and preserve package-specific shutdown and cleanup ordering.
  • Treat heuristic scanners as defense in depth, not as proof that arbitrary content is safe.

Signal acquisition and first-request shutdown ownership live in pkg/signals. A process must share one signals.ProcessShutdown across its monitors and declare exactly one semantic SIGINT owner; the package rejects duplicate or conflicting ownership. Start the process monitor before a composed print monitor and stop it after the print monitor so OS delivery remains continuously owned; an early process stop returns signals.ErrMonitorOrder without disarming delivery and may be retried after print stops. Cancellation and force-exit callbacks must be nonblocking, non-reentrant lifecycle leaves and must never invoke a monitor stop function. Generic staged cleanup, process, and filesystem lifecycle primitives remain in pkg/platform.

The isolated pkg/testing package owns the test-profile-only TestingPermission capability. It is registered only when an immutable environment snapshot explicitly contains NODE_ENV=test; conflicting values fail closed. The capability accepts exactly {}, is read-only and concurrency-safe, always requires the ordinary permission round trip with Run test?, and has no production registry footprint.

Directories

Path Synopsis
Package app assembles process-scoped services and dispatches presentation adapters.
 Package app assembles process-scoped services and dispatches presentation adapters.
Package attachment owns bounded, immutable user attachment imports.
 Package attachment owns bounded, immutable user attachment imports.
Package childenv owns the environment boundary for non-model child processes.
 Package childenv owns the environment boundary for non-model child processes.
Package cli performs mode-defining argument parsing before expensive runtime construction, ensuring diagnostics and stdout obey the selected surface.
 Package cli performs mode-defining argument parsing before expensive runtime construction, ensuring diagnostics and stdout obey the selected surface.
Package command defines user-invoked local routing.
 Package command defines user-invoked local routing.
Package compact models context pressure and summary projection without mutating the authoritative transcript.
 Package compact models context pressure and summary projection without mutating the authoritative transcript.
Package config loads, validates, and normalizes process configuration.
 Package config loads, validates, and normalizes process configuration.
Package distributed defines transport- and placement-neutral contracts for work that crosses a process or machine boundary.
 Package distributed defines transport- and placement-neutral contracts for work that crosses a process or machine boundary.
Package engine owns the shared, presentation-independent conversation turn loop.
 Package engine owns the shared, presentation-independent conversation turn loop.
Package extensions discovers and snapshots session-scoped extension descriptors.
 Package extensions discovers and snapshots session-scoped extension descriptors.
Package features models optional capability availability without collapsing build inclusion, gates, eligibility, policy, platform, configuration, user choice, and runtime health into one misleading Boolean.
 Package features models optional capability availability without collapsing build inclusion, gates, eligibility, policy, platform, configuration, user choice, and runtime health into one misleading Boolean.
Package identity defines identifiers whose distinct types prevent accidental correlation across session, turn, message, tool, task, and request domains.
 Package identity defines identifiers whose distinct types prevent accidental correlation across session, turn, message, tool, task, and request domains.
Package mcp implements the untrusted adapter boundary for Model Context Protocol providers.
 Package mcp implements the untrusted adapter boundary for Model Context Protocol providers.
Package memory provides bounded, provenance-bearing persistent memory.
 Package memory provides bounded, provenance-bearing persistent memory.
Package model defines the provider-neutral model transport boundary and the Azure OpenAI Responses API adapter.
 Package model defines the provider-neutral model transport boundary and the Azure OpenAI Responses API adapter.
Package observability consumes privacy-filtered copies of semantic events.
 Package observability consumes privacy-filtered copies of semantic events.
Package permission owns composed tool authorization.
 Package permission owns composed tool authorization.
Package platform owns portable operating-system mechanics and bounded resource cleanup.
 Package platform owns portable operating-system mechanics and bounded resource cleanup.
Package prompt builds deterministic model context independently of any presentation adapter or provider wire format.
 Package prompt builds deterministic model context independently of any presentation adapter or provider wire format.
Package protocol defines the versioned, presentation-independent event vocabulary exchanged by the session engine, capability runtime, transcript, and user-surface adapters.
 Package protocol defines the versioned, presentation-independent event vocabulary exchanged by the session engine, capability runtime, transcript, and user-surface adapters.
Package redact removes exact sensitive literals without allowing the replacement itself, adjacent context, or a later redaction pass to recreate a configured literal.
 Package redact removes exact sensitive literals without allowing the replacement itself, adjacent context, or a later redaction pass to recreate a configured literal.
Package sandbox owns optional operating-system process isolation.
 Package sandbox owns optional operating-system process isolation.
Package sessionlock owns the cross-process lease that prevents two runtimes from mutating one session's transcript and task state concurrently.
 Package sessionlock owns the cross-process lease that prevents two runtimes from mutating one session's transcript and task state concurrently.
Package signals owns process signal acquisition, first-request shutdown state, surface-specific interrupt routing, and bounded force-exit behavior.
 Package signals owns process signal acquisition, first-request shutdown state, surface-specific interrupt routing, and bounded force-exit behavior.
Package surface adapts the shared semantic runtime to user-visible input and output contracts.
 Package surface adapts the shared semantic runtime to user-visible input and output contracts.
Package task owns identity-bearing work that may outlive the tool call that launched it.
 Package task owns identity-bearing work that may outlive the tool call that launched it.
Package testing contains capabilities that exist only in the explicit test runtime profile.
 Package testing contains capabilities that exist only in the explicit test runtime profile.
Package tool implements the model-callable capability boundary: deterministic lookup, validation, authorization, execution, result pairing, and scheduling.
 Package tool implements the model-callable capability boundary: deterministic lookup, validation, authorization, execution, result pairing, and scheduling.
Package transcript owns append-only durable session history and defensive recovery.
 Package transcript owns append-only durable session history and defensive recovery.

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.