nvoken

package module
v0.33.0 Latest Latest
Warning

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

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

README

nvoken Go SDK

The Go SDK makes an nvoken Agent feel like a local runnable object while the service keeps each Turn durable. The ordinary path is intentionally small:

client, err := nvoken.NewClient(os.Getenv("NVOKEN_URL"), os.Getenv("NVOKEN_API_KEY"))
if err != nil {
	log.Fatal(err)
}

analyst, err := client.Agent(ctx, "real-estate-analyst")
if err != nil {
	log.Fatal(err)
}

answer, err := analyst.Text(ctx, "Compare these listings.", nvoken.TurnOptions{
	TenantKey: "acme",
	UserKey:   "alice",
})

client.Agent performs a lookup. App ownership is the default; pass AgentLookupOptions{OwnedBy: nvoken.TenantOwned("acme")} or nvoken.UserOwned("acme", "alice") for another owner namespace. Ownership selects which Agent you mean. The tenant and user on TurnOptions describe the actor for this execution; they do not change Agent ownership.

Start, run, and text

An Agent supports three levels of convenience:

turn, err := analyst.Start(ctx, "Compare these listings.", options)
result, err := analyst.Run(ctx, "Compare these listings.", options)
text, err := analyst.Text(ctx, "Compare these listings.", options)
  • Start admits a durable Turn and returns immediately.
  • Run waits for the Turn result and runs bound host tools when needed.
  • Text returns the final-answer text or NoOutputTextError.

Go cannot spell a parameter type that accepts both a bare string and []nvoken.InputBlock. TurnInput therefore keeps the compact string call and validates at runtime that the value is one of those two forms before sending a request. Other dynamic values fail locally with a validation error.

High-level create, publish, and Turn calls generate an idempotency key when you omit one. The same generated key is retained across automatic retries. Supply your own when the operation must be recovered across process boundaries.

Conversations and memory

Conversation continuity, Turn actor attribution, and MemorySpace selection are independent:

conversation := analyst.Conversation(nvoken.ConversationOptions{
	TenantKey: "acme",
	UserKey:   "alice",
	Selection: *nvoken.ContinueOrCreateConversation(
		"property-42",
		nvoken.TenantConversation(),
	),
	Memory: nvoken.UserMemory("analyst"),
})

answer, err := conversation.Text(ctx, "What changed?")

Use ContinueConversation(id) for an existing Conversation, or omit Conversation selection from ordinary TurnOptions for a standalone Turn. The Conversation handle binds its tenant, optional user, memory, and maximum limits together with its continuity selection. Per-call ConversationTurnOptions may add metadata, waiting behavior, an idempotency key, or narrower limits; it cannot replace the bound actor or memory.

Use NoneMemory(), TenantMemory(namespace), or UserMemory(namespace) to choose memory explicitly. A tenant MemorySpace can be intentionally shared across several users; user memory requires a Turn user.

Calls through Conversation handles for the same effective Conversation are serialized by their shared Client inside the current Go process. Durable concurrency policy remains a service concern; wire-exact conflict controls stay under raw Turn admission.

Inline behavior

An Agent is optional. Run behavior directly when it should not be published as a reusable AgentRevision:

classifier := client.Inline(nvoken.Behavior{
	Instructions: "Classify the message as billing, sales, or support.",
	Model:        model,
})

result, err := classifier.Run(ctx, message, nvoken.TurnOptions{
	TenantKey: "acme",
	Memory:    nvoken.NoneMemory(),
})

Host tools

Bind process-local handlers to an Agent or inline runner. Binding returns a new handle, so a shared Agent can safely use different handlers in different parts of an application.

analyst = analyst.BindTools(nvoken.Tool{
	Name: "lookup_listing",
	Handler: func(ctx context.Context, input any, call nvoken.TurnToolContext) (any, error) {
		log.Printf("handling %s for %s", call.ToolCallID, call.TurnID)
		return listings.Lookup(ctx, input)
	},
})

Run, Text, and Updates settle waiting host calls when a matching handler is bound. If no matching local handler is available, the durable Turn remains waiting; the caller can stop waiting and later recover the Turn with the right handler. Callback, builtin, and MCP calls are never executed by these local handlers.

Recovery and streaming

A Turn handle is local and performs no lookup until you use it:

turn := client.Turn("turn_...", nvoken.TurnAccess{
	TenantKey: "acme",
	UserKey:   "alice",
})

snapshot, err := turn.Status(ctx)
result, err := turn.Result(ctx)

Status is passive: it reads the current Turn plus its produced messages and final-answer text without driving tools. Result drives bound host tools and waits for a terminal Turn. Failed and cancelled work returns a TurnExecutionError carrying the complete terminal result. A local timeout returns TurnTimeoutError with the Turn and idempotency key needed for recovery. If the admission transport fails before its outcome is known, TurnAdmissionError retains the generated idempotency key so the exact request can be retried without creating a second Turn.

Persist the Turn ID and, when useful, turn.IdempotencyKey(). Bind the same host tools to a recovered handle before calling Result if it may be waiting for host work.

turn.Updates follows the direct Turn stream, folds replayable transcript updates with provisional message deltas, reconnects from the last durable cursor, and returns once the Turn's terminal change arrives:

err = turn.Updates(ctx, nvoken.UpdatesOptions{}, func(
	update nvoken.TurnUpdate,
) error {
	render(update.Snapshot, update.Previews)
	return nil
})

Each callback receives a reduced Turn snapshot, not a raw SSE frame. NewReducer remains available for applications that deliberately consume a Conversation stream through Raw() and want the same fold behavior.

Exact API access

The facade covers ordinary Agent execution. Administrative operations and any wire-exact feature are available without a second client:

response, err := client.Raw().ListConversationsWithResponse(ctx, params)

Raw() is the generated OpenAPI client. Its request and response types match the published HTTP contract exactly.

Documentation

Index

Constants

View Source 
const (
	// AskUserToolName is the well-known name. It carries no `nvoken_` prefix
	// because the host executes it, not the runtime.
	AskUserToolName = "ask_user"

	AskUserKindConfirm     = "confirm"
	AskUserKindSelect      = "select"
	AskUserKindMultiselect = "multiselect"
	AskUserKindInput       = "input"
)

A structured question to the end user is a host tool, not a new resource. The park/webhook/resume machinery already *is* "block until someone answers", so nvoken does not need a pending-interaction state or a response endpoint to deliver this. What it does need to supply is a standard shape, so the model and the host UI agree on what a question looks like without every integration inventing its own.

This is a convention, not runtime behaviour: nvoken treats AskUserToolName like any other host tool. Adopting it costs nothing and means a host UI written against one agent renders questions from another. The shape matches dive's toolkit ask_user, so an agent already written against that needs no translation layer.

View Source 
const (
	MaxMediaInputBlocks     = 8
	MaxImageInputBytes      = 5 << 20
	MaxDocumentInputBytes   = 16 << 20
	MaxMediaInputBytes      = 16 << 20
	MaxMediaTitleCharacters = 255
	MediaPreflightCode      = "media_preflight_failed"

	InputBlockTypeText     = "text"
	InputBlockTypeImage    = "image"
	InputBlockTypeDocument = "document"
)

Media input limits. They mirror the Runtime bounds so a mistake surfaces before a request is sent. Format sniffing, pixel bounds, and per-model modality support stay Runtime-side.

View Source 
const (
	MaxOutputSchemaBytes  = 32 * 1024
	MaxOutputSchemaDepth  = 16
	MaxOutputPatternBytes = 1024
	SchemaPreflightCode   = "schema_preflight_failed"
)
View Source 
const (
	WebhookEventWaiting    = generated.WebhookEventWaiting
	WebhookEventBudgetHold = generated.WebhookEventBudgetHold
	WebhookEventEnded      = generated.WebhookEventEnded
)
View Source 
const (
	TurnQueued     = generated.TurnStatusQueued
	TurnRunning    = generated.TurnStatusRunning
	TurnWaiting    = generated.TurnStatusWaiting
	TurnBudgetHold = generated.TurnStatusBudgetHold
	TurnCompleted  = generated.TurnStatusCompleted
	TurnIncomplete = generated.TurnStatusIncomplete
	TurnFailed     = generated.TurnStatusFailed
	TurnCancelled  = generated.TurnStatusCancelled

	ToolCallModeHost     = generated.ToolCallModeHost
	ToolCallModeCallback = generated.ToolCallModeCallback
	ToolCallModeBuiltin  = generated.ToolCallModeBuiltin
	ToolCallModeMCP      = generated.ToolCallModeMcp
)
View Source 
const (
	AppSigningKeyPurposeCallback    = generated.AppSigningKeyPurposeCallback
	AppSigningKeyPurposeWebhook     = generated.AppSigningKeyPurposeWebhook
	CredentialTypeInstallationAdmin = generated.CredentialTypeInstallationAdmin
	CredentialTypeApp               = generated.CredentialTypeApp
	CredentialTypeAppReadOnly       = generated.CredentialTypeAppReadOnly
	CredentialStatusActive          = generated.CredentialStatusActive
	CredentialStatusRevoked         = generated.CredentialStatusRevoked
	ArchiveStatusActive             = generated.ArchiveStatusActive
	ArchiveStatusAll                = generated.ArchiveStatusAll
	ArchiveStatusArchived           = generated.ArchiveStatusArchived
	ProviderKeyScopeApp             = generated.ProviderKeyScopeApp
	ProviderKeyScopeTenant          = generated.ProviderKeyScopeTenant
	ProviderKeyStatusActive         = generated.ProviderKeyStatusActive
	ProviderKeyStatusRevoked        = generated.ProviderKeyStatusRevoked
)
View Source 
const ClientTokenLifetimeLimit = 15 * time.Minute

ClientTokenLifetimeLimit is the longest a client token may live. nvoken refuses anything longer, so this is a ceiling rather than a suggestion.

Short lifetimes are the whole safety story of handing a browser a bearer token: the page refreshes from your backend on the schedule it already refreshes its own authentication, and a leaked token is worth minutes.

View Source 
const ClientTokenType = "nvoken-client+jwt"

ClientTokenType is the required `typ` header.

You sign these with a keypair you own and may sign other things with the same one. Without a type, `aud` is the only structural difference between a browser grant and any other EdDSA JWT you mint.

View Source 
const SignatureTimestampWindow = 5 * time.Minute

SignatureTimestampWindow is how far a delivery's signed timestamp may sit from the receiver's clock before the delivery is refused.

View Source 
const Version = "0.33.0"

Version is the released version of the Go SDK.

Variables

View Source 
var ErrStopStream = errors.New("stop reading the stream")

Functions

func AskUserInputSchema 

func AskUserInputSchema() map[string]any

AskUserInputSchema is the tool input schema, in the bounded subset nvoken admits. Declare a host tool with this schema and the model will produce questions an AskUserInput can decode.

func AskUserTool 

func AskUserTool(description string) generated.ToolDeclaration

AskUserTool is a ready-to-publish host tool contract. Bind the local handler separately with Tool{Name: AskUserToolName, Handler: handler}.

func DocumentMediaTypes 

func DocumentMediaTypes() []string

func ImageMediaTypes 

func ImageMediaTypes() []string

ImageMediaTypes and DocumentMediaTypes are the media types admission accepts.

func IsNotFound added in v0.22.0 

func IsNotFound(err error) bool

IsNotFound reports whether an SDK operation failed because the requested resource was not found or was outside the client's asserted scope.

func MintClientToken added in v0.22.0 

func MintClientToken(privateKey ed25519.PrivateKey, claims ClientTokenClaims) (string, error)

MintClientToken signs a browser grant with the App's client key.

Call it in backend code, never in a browser. The private key is the App's browser authority: a page holding it can mint any grant the ceiling allows, for any user, which is the failure this whole trust class exists to avoid.

func PreflightInputBlocks 

func PreflightInputBlocks(blocks []InputBlock) error

PreflightInputBlocks rejects locally checkable input problems using the same issue vocabulary the Runtime uses.

func PreflightOutputSchema 

func PreflightOutputSchema(schema map[string]any) error

func WebhookStatusIsRetried added in v0.22.0 

func WebhookStatusIsRetried(status int) bool

WebhookStatusIsRetried reports whether nvoken redelivers after a receiver answers with this status.

Any 5xx is retried, as are 408, 425, and 429. Every other non-2xx answer — 400, 401, 403, 404, 409, 410, 422 among them — is permanent, and the transition it described is never delivered again. Refusing a body that genuinely failed verification with 401 is therefore right: redelivering it would fail the same way. Refusing one because the signing key could not be read is not, and should answer RetryWebhook instead, since the two are indistinguishable to nvoken and only one of them is the sender's fault.

Types

type AdmissionAttempt added in v0.15.0 

type AdmissionAttempt = generated.AdmissionAttempt

type AdmissionAttemptList added in v0.15.0 

type AdmissionAttemptList = generated.AdmissionAttemptList

type AdmissionOutcome added in v0.15.0 

type AdmissionOutcome = generated.AdmissionOutcome

type AdmissionSummary added in v0.15.0 

type AdmissionSummary = generated.AdmissionSummary

type Agent 

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

Agent is a remotely resolved Agent and a directly runnable local handle.

func (*Agent) Archive added in v0.30.0 

func (a *Agent) Archive(ctx context.Context) (*Agent, error)

func (*Agent) BindTools added in v0.30.0 

func (a *Agent) BindTools(tools ...Tool) *Agent

func (*Agent) Conversation added in v0.30.0 

func (a *Agent) Conversation(options ConversationOptions) *Conversation

func (*Agent) Publish added in v0.30.0 

func (a *Agent) Publish(ctx context.Context, behavior Behavior, options PublishOptions) (*AgentRevision, error)

func (*Agent) Resource added in v0.21.0 

func (a *Agent) Resource() AgentResource

func (*Agent) Restore added in v0.30.0 

func (a *Agent) Restore(ctx context.Context) (*Agent, error)

func (*Agent) Run 

func (a *Agent) Run(ctx context.Context, input TurnInput, options TurnOptions) (*TurnResult, error)

func (*Agent) Start added in v0.29.0 

func (a *Agent) Start(ctx context.Context, input TurnInput, options TurnOptions) (*Turn, error)

func (*Agent) Text 

func (a *Agent) Text(ctx context.Context, input TurnInput, options TurnOptions) (string, error)

type AgentLookupOptions added in v0.30.0 

type AgentLookupOptions struct {
	OwnedBy AgentOwner
}

type AgentOwner added in v0.30.0 

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

AgentOwner selects the namespace in which an Agent key is looked up or created. Construct it with AppOwned, TenantOwned, or UserOwned so an empty tenant or user is rejected instead of silently selecting another namespace.

func AppOwned added in v0.30.0 

func AppOwned() AgentOwner

func TenantOwned added in v0.30.0 

func TenantOwned(tenant string) AgentOwner

func UserOwned added in v0.30.0 

func UserOwned(tenant, user string) AgentOwner

type AgentPage added in v0.30.0 

type AgentPage struct {
	Items      []*Agent
	HasMore    bool
	NextCursor *string
}

AgentPage preserves paging coordinates while keeping every returned item directly runnable through the same Client.

type AgentResource added in v0.21.0 

type AgentResource = generated.Agent

Exact resource projections. The handwritten facade deliberately gives the runnable handles distinct names; request-shaped control remains on Raw().

type AgentRevision added in v0.30.0 

type AgentRevision = generated.AgentRevision

type Agents added in v0.30.0 

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

func (*Agents) Create added in v0.30.0 

func (a *Agents) Create(ctx context.Context, options CreateAgentOptions) (*Agent, error)

func (*Agents) GetByID added in v0.30.0 

func (a *Agents) GetByID(ctx context.Context, id string) (*Agent, error)

func (*Agents) List added in v0.30.0 

func (a *Agents) List(ctx context.Context, options ListAgentsOptions) (*AgentPage, error)

type AllocateCreditsInput added in v0.14.0 

type AllocateCreditsInput struct {
	Amount         Money
	TenantKey      string
	Reference      *string
	IdempotencyKey string
}

type AllocateCreditsResult added in v0.14.0 

type AllocateCreditsResult = generated.AllocateCreditsResult

type AnonymousAccess added in v0.22.0 

type AnonymousAccess = generated.AnonymousAccess

type AnonymousTokenOptions added in v0.22.0 

type AnonymousTokenOptions struct {
	// IdempotencyKey names one logical exchange. Reuse it when retrying the
	// same request after an uncertain response.
	IdempotencyKey string
	// VisitorToken renews a previously issued visitor; omit it on a first visit.
	VisitorToken *string
	// HTTPClient replaces the default transport, primarily for applications
	// that need their own proxy, tracing, or timeout policy.
	HTTPClient *http.Client
}

AnonymousTokenOptions describes one credential-free visitor grant exchange.

type AnonymousTokenResponse added in v0.22.0 

type AnonymousTokenResponse = generated.AnonymousTokenResponse

func IssueAnonymousToken added in v0.22.0 

func IssueAnonymousToken(
	ctx context.Context,
	baseURL string,
	appID string,
	origin string,
	options AnonymousTokenOptions,
) (*AnonymousTokenResponse, error)

IssueAnonymousToken mints or renews credential-free browser access for one configured App. It never sends a machine credential.

type App 

type App = generated.App

Administrative aliases retained outside the runtime facade.

type AppDefaultRateLimits added in v0.22.0 

type AppDefaultRateLimits struct {
	MaxAdmissionsPerMinute int64
	MaxConcurrentTurns     int64
}

type AppList 

type AppList = generated.AppList

type AppRegistration 

type AppRegistration = generated.AppRegistration

type AppSigningKey added in v0.18.0 

type AppSigningKey = generated.AppSigningKey

type AppSigningKeyList added in v0.18.0 

type AppSigningKeyList = generated.AppSigningKeyList

type AppSigningKeyPurpose 

type AppSigningKeyPurpose = generated.AppSigningKeyPurpose

type AppSigningKeySecret 

type AppSigningKeySecret = generated.AppSigningKeySecret

type ArchiveStatus added in v0.14.0 

type ArchiveStatus = generated.ArchiveStatus

type AskUserInput 

type AskUserInput struct {
	Question  string          `json:"question"`
	Type      string          `json:"type"`
	Options   []AskUserOption `json:"options,omitempty"`
	Default   string          `json:"default,omitempty"`
	MinSelect int             `json:"min_select,omitempty"`
	MaxSelect int             `json:"max_select,omitempty"`
	Multiline bool            `json:"multiline,omitempty"`
}

AskUserInput is what the model sends.

type AskUserOption 

type AskUserOption struct {
	Value       string `json:"value"`
	Label       string `json:"label"`
	Description string `json:"description,omitempty"`
	Default     bool   `json:"default,omitempty"`
}

type AskUserOutput 

type AskUserOutput struct {
	Response string   `json:"response,omitempty"`
	Values   []string `json:"values,omitempty"`
	Canceled bool     `json:"canceled"`
}

AskUserOutput is what the host returns as the tool result. Canceled is not an error: a user declining to answer is a legitimate outcome the model should see and reason about, whereas an error result would read as a broken tool.

type Behavior added in v0.30.0 

type Behavior struct {
	Instructions string
	Model        ModelInput
	Tools        []ToolDeclaration
	Limits       *Limits
	OutputSchema *OutputSchema
	Memory       *DefaultMemoryPolicy
}

Behavior is the portable high-level behavior surface. Wire-exact provider, MCP, reasoning, sampling, client-token, and tool-choice controls remain on Raw().

type BrowserAccess added in v0.22.0 

type BrowserAccess struct {
	AllowedOrigins []string
	TurnWebhook    BrowserTurnWebhook
	Limits         BrowserRateLimits
}

type BrowserConversationGrant added in v0.30.0 

type BrowserConversationGrant struct {
	ConversationID string `json:"conversation_id,omitempty"`
	Scope          string `json:"scope"`
}

BrowserConversationGrant is the Conversation authority carried by a client token: standalone Turns only, one exact Conversation, or any user-owned Conversation for the token subject.

func BrowserExactConversation added in v0.30.0 

func BrowserExactConversation(id string) BrowserConversationGrant

func BrowserStandaloneOnly added in v0.30.0 

func BrowserStandaloneOnly() BrowserConversationGrant

func BrowserUserConversations added in v0.30.0 

func BrowserUserConversations() BrowserConversationGrant

type BrowserMemoryGrant added in v0.30.0 

type BrowserMemoryGrant struct {
	Namespace string `json:"namespace,omitempty"`
	Scope     string `json:"scope"`
}

BrowserMemoryGrant is the memory authority carried by a client token. A browser may use no memory or one user MemorySpace namespace; tenant-shared memory remains server-side authority.

func BrowserNoMemory added in v0.30.0 

func BrowserNoMemory() BrowserMemoryGrant

func BrowserUserMemory added in v0.30.0 

func BrowserUserMemory(namespace string) BrowserMemoryGrant

type BrowserRateLimits added in v0.22.0 

type BrowserRateLimits struct {
	MaxAdmissionsPerUserPerMinute int64
	MaxConcurrentTurnsPerTenant   int64
	MaxConcurrentTurnsPerUser     int64
}

type BrowserTurnWebhook added in v0.30.0 

type BrowserTurnWebhook struct {
	URL    string
	Events []WebhookEvent
}

type CallbackDelivery added in v0.22.0 

type CallbackDelivery struct {
	Reply   CallbackReply
	Outcome CallbackOutcome
	Reason  string
	// Delivery is set once the signature checked out, whatever happened after.
	Delivery VerifiedCallback
	Verified bool
	// Cause is the error behind a refused or failed outcome, for the host's
	// logger. It is never rendered into the reply.
	Cause error
}

CallbackDelivery is one answered delivery: the reply the host writes, and enough about what happened to log it.

Reason is a stable token for a log line and is never echoed into the reply body, because nvoken is not the audience for it and a refused sender should learn nothing.

type CallbackEnvelope 

type CallbackEnvelope struct {
	Nvoken generated.ToolCallbackContext `json:"nvoken"`
	Input  json.RawMessage               `json:"input"`
}

type CallbackOutcome added in v0.22.0 

type CallbackOutcome string

CallbackOutcome is what a receiver did with one delivery.

It is what the status alone cannot say — a 200 that replayed a recorded answer did no work. 

const (
	CallbackSettled      CallbackOutcome = "settled"
	CallbackAcknowledged CallbackOutcome = "acknowledged"
	CallbackReplayed     CallbackOutcome = "replayed"
	CallbackRefused      CallbackOutcome = "refused"
	CallbackFailed       CallbackOutcome = "failed"
)

type CallbackReceiver added in v0.22.0 

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

CallbackReceiver answers a tool-callback endpoint: key selection, signature verification, dispatch on the signed tool name, deduplication, and the reply discipline nvoken reads.

That discipline is the part worth having in one place, because every status here is a decision about whether nvoken tries again: 

no keys configured                        503  an operator error, still fixable inside the retry window
signing identity not held                 401  a real identity failure; redelivery reproduces it
signature, timestamp, or envelope invalid 401  the same bytes fail the same way
no handler for the signed tool name       400  nothing here can ever run it
handler returned a reply             200/202  the tool answered, or took the call away
handler returned an error                 503  the receiver failed, not the tool — and the store makes retrying safe

A tool that failed is not a receiver that failed. Settle it with CallbackResult(reason, true): the model can read a tool error and correct itself, while a 5xx only has nvoken deliver the same doomed call again.

The endpoint is public because nvoken must reach it, and it is not anonymous: nothing below the signature check runs until the HMAC over the raw bytes verifies.

func NewCallbackReceiver added in v0.22.0 

func NewCallbackReceiver(options CallbackReceiverOptions) (*CallbackReceiver, error)

NewCallbackReceiver builds a receiver, refusing a key table that could only fail later at delivery time.

func (*CallbackReceiver) Handle added in v0.22.0 

func (r *CallbackReceiver) Handle(ctx context.Context, header http.Header, rawBody []byte) CallbackDelivery

Handle answers one delivery. It never returns an error: everything that can go wrong is a status nvoken understands, and the outcome says which.

type CallbackReceiverOptions added in v0.22.0 

type CallbackReceiverOptions struct {
	// Keys is every secret this endpoint accepts. Two entries span a rotation.
	Keys []DeliverySigningKey
	// Tools maps the tool name nvoken signs into the body to its handler.
	Tools map[string]CallbackToolHandler
	// Store is where answered ToolCalls are recorded. Leave it nil only when
	// every tool here is safe to run twice: without a store, a redelivery runs
	// the tool again.
	Store CallbackResultStore
	Now   func() time.Time
}

CallbackReceiverOptions configures a receiver.

type CallbackReply added in v0.12.0 

type CallbackReply struct {
	Status int
	Body   []byte
}

CallbackReply is the HTTP answer to one callback delivery. Rendering it is left to the host's web framework: write Status, and Body when it is not empty.

func AcknowledgeCallback added in v0.12.0 

func AcknowledgeCallback() CallbackReply

AcknowledgeCallback accepts delivery without settling the ToolCall, for work that will outlive this tool's reply deadline — its declared timeout_seconds, or the App's default when it declares none. Settle it later with Raw().SubmitHostToolResults, reusing the delivery's ToolCall ID.

This trades away the fail-loud guarantee. nvoken marks an unacknowledged delivery failed once its retries are exhausted, so the turn always moves on. An acknowledged call instead waits under the host's responsibility, bounded only by the Turn's Limits.WaitingTimeoutSeconds. Acknowledge only when something durable will settle the call.

func CallbackResult added in v0.12.0 

func CallbackResult(content any, isError bool) (CallbackReply, error)

CallbackResult settles the ToolCall inline. Content may be any JSON value, encoded to at most 256 KiB and 32 levels of nesting. The turn resumes as soon as nvoken records the reply.

type CallbackResultStore 

type CallbackResultStore interface {
	Find(ctx context.Context, toolCallID string) (reply CallbackReply, found bool, err error)
	PutIfAbsent(ctx context.Context, toolCallID string, reply CallbackReply) (stored CallbackReply, inserted bool, err error)
}

CallbackResultStore is where a receiver records what it already answered, so a redelivery returns that answer instead of running the tool again.

Both operations are needed and they are needed in this order. Find runs before the tool does, because a redelivery that re-runs it repeats every effect it had. PutIfAbsent runs after, because two deliveries of one ToolCall can be in flight at once and only one answer may win.

type CallbackToolHandler added in v0.22.0 

type CallbackToolHandler func(ctx context.Context, delivery VerifiedCallback) (CallbackReply, error)

CallbackToolHandler runs one tool for one delivery. Return the reply — CallbackResult to settle the call, AcknowledgeCallback to take it away and settle it later.

A tool that failed still returns: CallbackResult(reason, true) settles the call carrying is_error, which the model can read and correct itself against. Returning an error means something in the receiver failed, not the tool, and answers 503 so nvoken redelivers.

type Client 

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

func NewClient 

func NewClient(baseURL, apiKey string, options ...ClientOption) (*Client, error)

func (*Client) ActivateAppSigningKey added in v0.18.0 

func (c *Client) ActivateAppSigningKey(
	ctx context.Context,
	appID string,
	purpose AppSigningKeyPurpose,
	version int64,
) (*AppSigningKey, error)

ActivateAppSigningKey moves signing to an existing version. The transport resolves the key per send, so it takes effect on the next delivery. Do this only once your receiver verifies against that version's secret.

func (*Client) Agent 

func (c *Client) Agent(ctx context.Context, key string, options ...AgentLookupOptions) (*Agent, error)

Agent resolves one Agent key now. App ownership is the unmarked common case; pass one AgentLookupOptions for a tenant- or user-owned Agent.

func (*Client) Agents added in v0.30.0 

func (c *Client) Agents() *Agents

Agents returns the management collection. Runnable hot paths normally use Client.Agent directly.

func (*Client) AllocateCredits added in v0.14.0 

func (c *Client) AllocateCredits(ctx context.Context, input AllocateCreditsInput) (*AllocateCreditsResult, error)

func (*Client) ArchiveApp added in v0.14.0 

func (c *Client) ArchiveApp(ctx context.Context, appID string) error

func (*Client) ArchiveOrg added in v0.14.0 

func (c *Client) ArchiveOrg(ctx context.Context, orgID string) error

func (*Client) CreateAppClientKey added in v0.14.0 

func (c *Client) CreateAppClientKey(ctx context.Context, appID string, input CreateAppClientKeyInput) (*ClientKey, error)

func (*Client) CreateCredential 

func (c *Client) CreateCredential(
	ctx context.Context,
	input CreateCredentialInput,
) (*CredentialIssuance, error)

func (*Client) CreateProviderKey 

func (c *Client) CreateProviderKey(
	ctx context.Context,
	input CreateProviderKeyInput,
) (*ProviderKey, error)

func (*Client) DeleteTenant added in v0.15.0 

func (c *Client) DeleteTenant(ctx context.Context, id string) error

func (*Client) EachProviderKey 

func (c *Client) EachProviderKey(
	ctx context.Context,
	options ListProviderKeysOptions,
	consume func(ProviderKey) error,
) error

func (*Client) GetApp 

func (c *Client) GetApp(ctx context.Context, appID string) (*App, error)

func (*Client) GetCredential 

func (c *Client) GetCredential(ctx context.Context, credentialID string) (*Credential, error)

func (*Client) GetCurrentIdentity 

func (c *Client) GetCurrentIdentity(ctx context.Context) (*CurrentIdentity, error)

func (*Client) GetModel 

func (c *Client) GetModel(ctx context.Context, model Model) (*ModelDescriptor, error)

func (*Client) GetOrg added in v0.11.0 

func (c *Client) GetOrg(ctx context.Context, orgID string) (*Org, error)

func (*Client) GetProviderKey 

func (c *Client) GetProviderKey(ctx context.Context, id string) (*ProviderKey, error)

func (*Client) GetProviderKeyUsage 

func (c *Client) GetProviderKeyUsage(ctx context.Context, id string) (*ProviderKeyUsage, error)

func (*Client) GetUsageBreakdown added in v0.11.0 

func (c *Client) GetUsageBreakdown(ctx context.Context, params *GetUsageBreakdownParams) (*UsageBreakdown, error)

func (*Client) GetUsageTimeseries added in v0.11.0 

func (c *Client) GetUsageTimeseries(ctx context.Context, params *GetUsageTimeseriesParams) (*UsageTimeseries, error)

func (*Client) Inline added in v0.30.0 

func (c *Client) Inline(behavior Behavior) *InlineRunner

func (*Client) ListAdmissions added in v0.15.0 

func (c *Client) ListAdmissions(ctx context.Context, params *ListAdmissionsParams) (*AdmissionAttemptList, error)

func (*Client) ListAppClientKeys added in v0.14.0 

func (c *Client) ListAppClientKeys(ctx context.Context, appID string) (*ClientKeyList, error)

func (*Client) ListAppSigningKeys added in v0.18.0 

func (c *Client) ListAppSigningKeys(ctx context.Context, appID string) (*AppSigningKeyList, error)

ListAppSigningKeys returns every receiver-facing signing key version an App holds and marks the one that signs. Key material is never returned.

func (*Client) ListApps 

func (c *Client) ListApps(ctx context.Context, options ListAppsOptions) (*AppList, error)

func (*Client) ListCredentials 

func (c *Client) ListCredentials(
	ctx context.Context,
	options ListCredentialsOptions,
) (*CredentialList, error)

func (*Client) ListCreditAccounts added in v0.14.0 

func (c *Client) ListCreditAccounts(ctx context.Context, params *ListCreditAccountsParams) (*CreditAccountList, error)

func (*Client) ListCreditAllocations added in v0.14.0 

func (c *Client) ListCreditAllocations(ctx context.Context, params *ListCreditAllocationsParams) (*CreditAllocationList, error)

func (*Client) ListMCPTools 

func (c *Client) ListMCPTools(
	ctx context.Context,
	server MCPServer,
	headers map[string]string,
) (*MCPListToolsResponse, error)

ListMCPTools discovers the tools a remote MCP server projects. Headers are a separate argument because MCPServer is durable AgentRevision configuration and therefore carries no secrets; these are used for this one discovery request and never stored.

func (*Client) ListModels 

func (c *Client) ListModels(
	ctx context.Context,
	options ListModelsOptions,
) (*ModelList, error)

func (*Client) ListOrgs added in v0.11.0 

func (c *Client) ListOrgs(ctx context.Context, options ListOrgsOptions) (*OrgList, error)

func (*Client) ListProviderKeys 

func (c *Client) ListProviderKeys(
	ctx context.Context,
	options ListProviderKeysOptions,
) (*ProviderKeyList, error)

func (*Client) ListTenants added in v0.15.0 

func (c *Client) ListTenants(ctx context.Context, params *ListTenantsParams) (*TenantList, error)

func (*Client) ListUsageRecords added in v0.11.0 

func (c *Client) ListUsageRecords(ctx context.Context, params *ListUsageRecordsParams) (*UsageRecords, error)

ListUsageRecords returns the JSON representation. Use Raw when requesting the CSV representation so the response body and continuation header remain available without lossy conversion.

func (*Client) MintAppSigningKey added in v0.18.0 

func (c *Client) MintAppSigningKey(
	ctx context.Context,
	appID string,
	input MintAppSigningKeyInput,
) (*AppSigningKeySecret, error)

MintAppSigningKey writes the next version for one purpose and returns its plaintext exactly once. There is no way to read it again.

nvoken keeps signing with the current version. Add the returned secret to your verifier beside the one already there, then ActivateAppSigningKey, then RetireAppSigningKey. In that order no delivery ever fails verification, which matters because a receiver's 401 is not retried: it settles the ToolCall as a delivery failure.

Set input.Activate only when there is no working verifier left to protect — recovering a lost secret, where the three steps collapse into this one.

func (*Client) Raw 

func (c *Client) Raw() *generated.ClientWithResponses

func (*Client) RegisterApp 

func (c *Client) RegisterApp(ctx context.Context, name string, options RegisterAppOptions) (*AppRegistration, error)

RegisterApp registers one host application and returns its generated app_id. It requires an installation-admin key or a trusted Console presentation.

func (*Client) RegisterOrg added in v0.11.0 

func (c *Client) RegisterOrg(ctx context.Context, displayName string, options RegisterOrgOptions) (*Org, error)

func (*Client) RestoreApp added in v0.14.0 

func (c *Client) RestoreApp(ctx context.Context, appID string) error

func (*Client) RestoreOrg added in v0.14.0 

func (c *Client) RestoreOrg(ctx context.Context, orgID string) error

func (*Client) RetireAppSigningKey added in v0.18.0 

func (c *Client) RetireAppSigningKey(
	ctx context.Context,
	appID string,
	purpose AppSigningKeyPurpose,
	version int64,
) error

RetireAppSigningKey deletes a superseded version once signing has moved off it and your receiver has dropped it. Retiring the version that is signing is refused rather than silently silencing every delivery the App makes.

func (*Client) RevokeAppClientKey added in v0.14.0 

func (c *Client) RevokeAppClientKey(ctx context.Context, appID, keyID string) error

func (*Client) RevokeCredential 

func (c *Client) RevokeCredential(ctx context.Context, credentialID string) (*Credential, error)

func (*Client) RevokeProviderKey 

func (c *Client) RevokeProviderKey(ctx context.Context, id string) (*ProviderKey, error)

func (*Client) RotateCredential 

func (c *Client) RotateCredential(
	ctx context.Context,
	credentialID string,
	input RotateCredentialInput,
) (*CredentialIssuance, error)

func (*Client) RotateProviderKey 

func (c *Client) RotateProviderKey(
	ctx context.Context,
	id string,
	input RotateProviderKeyInput,
) (*ProviderKey, error)

func (*Client) SummarizeAdmissions added in v0.15.0 

func (c *Client) SummarizeAdmissions(ctx context.Context, params *SummarizeAdmissionsParams) (*AdmissionSummary, error)

func (*Client) Turn added in v0.30.0 

func (c *Client) Turn(id string, access TurnAccess) *Turn

Turn constructs a local recovery handle. The first remote operation checks visibility using the credential and explicit access coordinates.

func (*Client) UpdateApp 

func (c *Client) UpdateApp(ctx context.Context, appID string, options UpdateAppOptions) (*App, error)

UpdateApp changes an App's mutable configuration: its presentation, its admission ceilings, its credit policy, and whether browser-direct and anonymous callers are allowed. Name and external_ref cannot be changed.

func (*Client) UpdateOrg added in v0.11.0 

func (c *Client) UpdateOrg(ctx context.Context, orgID, displayName string) (*Org, error)

type ClientKey added in v0.14.0 

type ClientKey = generated.ClientKey

type ClientKeyList added in v0.14.0 

type ClientKeyList = generated.ClientKeyList

type ClientOption 

type ClientOption func(*clientOptions)

func WithHTTPClient 

func WithHTTPClient(client *http.Client) ClientOption

func WithRetryPolicy 

func WithRetryPolicy(policy RetryPolicy) ClientOption

type ClientTokenClaims added in v0.22.0 

type ClientTokenClaims struct {
	// AppID is the App this token acts inside. It becomes the `iss` claim.
	AppID string
	// KeyID names the registered client key that verifies this token,
	// as returned by `nvoken client-key create`. It becomes `kid`.
	KeyID string
	// Subject identifies the end user to nvoken. It is opaque: nvoken stores
	// it as the runtime user constraint and never resolves it to a person, so
	// prefer an internal id over an email address.
	Subject string
	// TenantKey scopes the token to one tenant.
	TenantKey string
	// AgentID pins the exact Agent the browser may run.
	AgentID string
	// AgentRevisionID pins the exact immutable behavior the browser may run.
	AgentRevisionID string
	// MemoryAccess is the browser's closed memory grant.
	MemoryAccess BrowserMemoryGrant
	// ConversationAccess is the browser's closed Conversation grant.
	ConversationAccess BrowserConversationGrant
	// IssuedAt defaults to the current time.
	IssuedAt time.Time
	// Lifetime is required and may not exceed ClientTokenLifetimeLimit.
	Lifetime time.Duration
}

ClientTokenClaims is what a host asserts when it lets a browser talk to nvoken directly.

Every field here narrows what the browser can do. nvoken cannot second-guess a signed claim — it trusts what you assert, exactly as it trusts your API key — so the narrowing is yours to do, and MintClientToken refuses a grant nvoken would refuse rather than handing you a token that fails in a browser.

type Conversation added in v0.30.0 

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

Conversation fixes continuity, actor, memory, and maximum limits. Calls through one handle are serialized in this process.

func (*Conversation) Run added in v0.30.0 

func (c *Conversation) Run(ctx context.Context, input TurnInput, options ...ConversationTurnOptions) (*TurnResult, error)

func (*Conversation) Start added in v0.30.0 

func (c *Conversation) Start(ctx context.Context, input TurnInput, options ...ConversationTurnOptions) (*Turn, error)

func (*Conversation) Text added in v0.30.0 

func (c *Conversation) Text(ctx context.Context, input TurnInput, options ...ConversationTurnOptions) (string, error)

type ConversationMessage added in v0.30.0 

type ConversationMessage = generated.ConversationMessage

type ConversationOptions added in v0.30.0 

type ConversationOptions struct {
	TenantKey string
	UserKey   string
	Selection ConversationSelection
	Memory    *MemorySelection
	Limits    *Limits
}

ConversationOptions binds all execution context that must stay fixed across calls through one local Conversation handle.

type ConversationOwner added in v0.30.0 

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

func TenantConversation added in v0.30.0 

func TenantConversation() ConversationOwner

func UserConversation added in v0.30.0 

func UserConversation(user string) ConversationOwner

type ConversationResource added in v0.30.0 

type ConversationResource = generated.Conversation

type ConversationSelection added in v0.30.0 

type ConversationSelection struct {
	ID       string
	Key      string
	Owner    ConversationOwner
	Metadata map[string]any
}

ConversationSelection selects existing continuity by ID or atomically resolves a caller-owned key with continue-or-create semantics.

func ContinueConversation added in v0.30.0 

func ContinueConversation(id string) *ConversationSelection

func ContinueOrCreateConversation added in v0.30.0 

func ContinueOrCreateConversation(key string, owner ConversationOwner) *ConversationSelection

type ConversationTurnOptions added in v0.30.0 

type ConversationTurnOptions struct {
	IdempotencyKey string
	Metadata       map[string]string
	Limits         *Limits
	Wait           WaitOptions
}

ConversationTurnOptions contains only facts a Conversation call may vary. Limits may narrow, but never widen, the binding's limits.

type CreateAgentOptions added in v0.30.0 

type CreateAgentOptions struct {
	Key            string
	Name           string
	OwnedBy        AgentOwner
	Behavior       Behavior
	IdempotencyKey string
}

type CreateAppClientKeyInput added in v0.14.0 

type CreateAppClientKeyInput struct {
	Name      string
	PublicKey []byte
}

type CreateCredentialInput 

type CreateCredentialInput struct {
	Name           string
	Type           CredentialType
	AppID          *string
	ExpiresAt      *time.Time
	IdempotencyKey string
}

type CreateProviderKeyInput 

type CreateProviderKeyInput struct {
	Provider       ModelProvider
	Scope          ProviderKeyScope
	TenantKey      *string
	APIKey         string
	ExpiresAt      *time.Time
	IdempotencyKey string
}

type Credential 

type Credential = generated.Credential

type CredentialIssuance 

type CredentialIssuance struct {
	Credential        Credential
	Secret            string
	DeliveryExpiresAt time.Time
	Replayed          bool
}

type CredentialList 

type CredentialList = generated.CredentialList

type CredentialStatus 

type CredentialStatus = generated.CredentialStatus

type CredentialType added in v0.28.0 

type CredentialType = generated.CredentialType

type CreditAccount added in v0.14.0 

type CreditAccount = generated.CreditAccount

type CreditAccountList added in v0.14.0 

type CreditAccountList = generated.CreditAccountList

type CreditAllocation added in v0.14.0 

type CreditAllocation = generated.CreditAllocation

type CreditAllocationList added in v0.14.0 

type CreditAllocationList = generated.CreditAllocationList

type CreditBlock added in v0.22.0 

type CreditBlock = generated.CreditBlock

type CreditPolicy added in v0.22.0 

type CreditPolicy string
const (
	CreditPolicyOff      CreditPolicy = "off"
	CreditPolicyRequired CreditPolicy = "required"
)

type CurrentIdentity 

type CurrentIdentity = generated.CurrentIdentity

type DefaultMemoryPolicy added in v0.30.0 

type DefaultMemoryPolicy = generated.DefaultMemoryPolicy

type DeliveryKeyError added in v0.22.0 

type DeliveryKeyError struct {
	Reason    string
	Retryable bool
}

DeliveryKeyError says why a receiver would not accept a delivery's signing identity.

Retryable is the whole point of the distinction. An unconfigured receiver is an operator error this deployment may still fix inside nvoken's retry window. A configured receiver that does not know this key version is a real signing-identity failure, and asking for redelivery only reproduces it.

func (*DeliveryKeyError) Error added in v0.22.0 

func (e *DeliveryKeyError) Error() string

type DeliverySigningKey added in v0.22.0 

type DeliverySigningKey struct {
	KeyID   string
	Version int64
	// Secret is at least 32 bytes.
	Secret []byte
}

DeliverySigningKey is one secret a receiver will accept deliveries signed with.

The key id names the App and the purpose and does not change; the version selects the secret within it. Holding two versions is what makes a rotation survivable — nvoken mints the next version while still signing with the current one, and a signature a receiver cannot verify fails its delivery outright rather than retrying, so there is no forgiveness to lean on.

Version is an integer rather than the string it arrives as in configuration on purpose. A version that cannot be read as a positive integer makes the receiver refuse to be built, which is loud, instead of refusing live deliveries, which is permanent.

type Error 

type Error struct {
	Category   ErrorCategory
	Status     int
	Code       string
	Message    string
	RequestID  string
	RetryAfter time.Duration
	Details    map[string]any
	Cause      error
}

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Unwrap 

func (e *Error) Unwrap() error

type ErrorCategory 

type ErrorCategory string
const (
	ErrorAuthentication     ErrorCategory = "authentication"
	ErrorPermission         ErrorCategory = "permission"
	ErrorValidation         ErrorCategory = "validation"
	ErrorNotFound           ErrorCategory = "not_found"
	ErrorConflict           ErrorCategory = "conflict"
	ErrorRateLimit          ErrorCategory = "rate_limit"
	ErrorServer             ErrorCategory = "server"
	ErrorTransport          ErrorCategory = "transport"
	ErrorCancelled          ErrorCategory = "cancelled"
	ErrorTimeout            ErrorCategory = "timeout"
	ErrorUnexpectedResponse ErrorCategory = "unexpected_response"
)

type GetUsageBreakdownParams added in v0.11.0 

type GetUsageBreakdownParams = generated.GetUsageBreakdownParams

type GetUsageBreakdownParamsGroupBy added in v0.11.0 

type GetUsageBreakdownParamsGroupBy = generated.GetUsageBreakdownParamsGroupBy

type GetUsageBreakdownParamsSort added in v0.11.0 

type GetUsageBreakdownParamsSort = generated.GetUsageBreakdownParamsSort

type GetUsageTimeseriesParams added in v0.11.0 

type GetUsageTimeseriesParams = generated.GetUsageTimeseriesParams

type GetUsageTimeseriesParamsGroupBy added in v0.11.0 

type GetUsageTimeseriesParamsGroupBy = generated.GetUsageTimeseriesParamsGroupBy

type InlineRunner added in v0.30.0 

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

InlineRunner runs immutable behavior without creating an Agent.

func (*InlineRunner) BindTools added in v0.30.0 

func (r *InlineRunner) BindTools(tools ...Tool) *InlineRunner

func (*InlineRunner) Conversation added in v0.30.0 

func (r *InlineRunner) Conversation(options ConversationOptions) *Conversation

func (*InlineRunner) Run added in v0.30.0 

func (r *InlineRunner) Run(ctx context.Context, input TurnInput, options TurnOptions) (*TurnResult, error)

func (*InlineRunner) Start added in v0.30.0 

func (r *InlineRunner) Start(ctx context.Context, input TurnInput, options TurnOptions) (*Turn, error)

func (*InlineRunner) Text added in v0.30.0 

func (r *InlineRunner) Text(ctx context.Context, input TurnInput, options TurnOptions) (string, error)

type InputBlock 

type InputBlock struct {
	Type   string
	Text   string
	Source *InputBlockSource
	Title  string
}

InputBlock is one ordered caller-input block.

func DocumentInputBlock 

func DocumentInputBlock(mediaType, data, title string) InputBlock

DocumentInputBlock inlines document bytes that are already base64 encoded. An empty title uses the provider adapter default.

func DocumentURLInputBlock 

func DocumentURLInputBlock(sourceURL, title string) InputBlock

DocumentURLInputBlock builds a PDF fetched once by nvoken during admission.

func ImageInputBlock 

func ImageInputBlock(mediaType, data string) InputBlock

ImageInputBlock inlines image bytes that are already base64 encoded.

func ImageURLInputBlock 

func ImageURLInputBlock(sourceURL string) InputBlock

ImageURLInputBlock builds an image fetched once by nvoken during admission.

func TextInputBlock 

func TextInputBlock(text string) InputBlock

TextInputBlock builds the ordinary text input block.

type InputBlockSource 

type InputBlockSource struct {
	MediaType string
	Data      string
	URL       string
}

InputBlockSource carries inline media bytes or one public HTTPS URL.

type Limits 

type Limits = generated.Limits

type ListAdmissionsParams added in v0.15.0 

type ListAdmissionsParams = generated.ListAdmissionsParams

type ListAgentsOptions 

type ListAgentsOptions struct {
	OwnedBy  AgentOwner
	Archived bool
	Cursor   string
	Limit    int
}

type ListAppsOptions 

type ListAppsOptions struct {
	ExternalRef *string
	Status      *ArchiveStatus
}

type ListCredentialsOptions 

type ListCredentialsOptions struct {
	Status *CredentialStatus
	Cursor *string
	Limit  *int
}

type ListCreditAccountsParams added in v0.14.0 

type ListCreditAccountsParams = generated.ListCreditAccountsParams

type ListCreditAllocationsParams added in v0.14.0 

type ListCreditAllocationsParams = generated.ListCreditAllocationsParams

type ListModelsOptions 

type ListModelsOptions struct {
	Provider          *ModelProvider
	IncludeDeprecated *bool
}

type ListOrgsOptions added in v0.14.0 

type ListOrgsOptions struct{ Status *ArchiveStatus }

type ListProviderKeysOptions 

type ListProviderKeysOptions struct {
	Provider  *ModelProvider
	Scope     *ProviderKeyScope
	Status    *ProviderKeyStatus
	TenantKey *string
	Cursor    *string
	Limit     *int
}

type ListTenantsParams added in v0.15.0 

type ListTenantsParams = generated.ListTenantsParams

type ListUsageRecordsParams added in v0.11.0 

type ListUsageRecordsParams = generated.ListUsageRecordsParams

type ListUsageRecordsParamsFormat added in v0.11.0 

type ListUsageRecordsParamsFormat = generated.ListUsageRecordsParamsFormat

type MCPListToolsResponse 

type MCPListToolsResponse = generated.MCPListToolsResponse

type MCPServer 

type MCPServer = generated.MCPServer

type MCPTimeouts 

type MCPTimeouts = generated.MCPTimeouts

type MachineConcurrencyLimits added in v0.22.0 

type MachineConcurrencyLimits struct {
	MaxConcurrentTurnsPerTenant int64
	MaxConcurrentTurnsPerUser   int64
}

type MediaIssue 

type MediaIssue struct {
	Code    string
	Path    string
	Message string
}

type MemorySelection added in v0.30.0 

type MemorySelection struct {
	Scope     string
	Namespace string
}

MemorySelection is one explicit per-Turn memory choice. Nil means use the selected behavior's default. NoneMemory disables memory.

func NoneMemory added in v0.30.0 

func NoneMemory() *MemorySelection

func TenantMemory added in v0.30.0 

func TenantMemory(namespace string) *MemorySelection

func UserMemory added in v0.30.0 

func UserMemory(namespace string) *MemorySelection

type MemorySpace added in v0.30.0 

type MemorySpace = generated.MemorySpace

type MemorySpaceList added in v0.30.0 

type MemorySpaceList = generated.MemorySpaceList

type Metadata added in v0.30.0 

type Metadata = generated.Metadata

type MintAppSigningKeyInput added in v0.18.0 

type MintAppSigningKeyInput struct {
	Purpose  AppSigningKeyPurpose
	Activate bool
}

type Model 

type Model = generated.Model

type ModelDescriptor 

type ModelDescriptor = generated.ModelDescriptor

type ModelInput added in v0.30.0 

type ModelInput = generated.ModelInput

type ModelList 

type ModelList struct {
	CatalogVersion string            `json:"catalog_version"`
	Items          []ModelDescriptor `json:"items"`
}

type ModelPricing 

type ModelPricing = generated.ModelPricing

type ModelProvider 

type ModelProvider = generated.ModelProvider

type Money added in v0.11.0 

type Money = generated.Money

type NoOutputTextError 

type NoOutputTextError struct {
	TurnID string
}

func (*NoOutputTextError) Error 

func (e *NoOutputTextError) Error() string

type Nudge 

type Nudge = generated.Nudge

type NudgeAcknowledgement 

type NudgeAcknowledgement = generated.NudgeAcknowledgement

type NudgeList 

type NudgeList = generated.NudgeList

type NudgeStatus 

type NudgeStatus = generated.NudgeStatus

type Org added in v0.11.0 

type Org = generated.Org

type OrgList added in v0.11.0 

type OrgList = generated.OrgList

type OutputSchema added in v0.30.0 

type OutputSchema = generated.OutputSchema

type Probe added in v0.22.0 

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

Probe reads a deployment's liveness and readiness endpoints.

It takes no credential, because neither endpoint requires one. That is the point: a probe that needed a key could not tell "the deployment is down" apart from "this key is wrong", and those call for opposite responses.

func NewProbe added in v0.22.0 

func NewProbe(baseURL string, options ...ProbeOption) (*Probe, error)

NewProbe returns a Probe for one deployment.

func (*Probe) Health added in v0.22.0 

func (p *Probe) Health(ctx context.Context) (ProbeResult, error)

Health reports whether the process is running. It touches no dependency, so it stays honest as a restart signal — a database being down is not a reason to kill the process.

func (*Probe) Readiness added in v0.22.0 

func (p *Probe) Readiness(ctx context.Context) (ProbeResult, error)

Readiness reports whether the process can serve requests, which means the database answered. Route traffic on this rather than on Health: nvoken's execution authority is Postgres, so a process that cannot reach it has nothing to serve.

type ProbeOption added in v0.22.0 

type ProbeOption func(*Probe)

func WithProbeHTTPClient added in v0.22.0 

func WithProbeHTTPClient(client *http.Client) ProbeOption

WithProbeHTTPClient replaces the HTTP client the probe uses. Give it a short timeout: a probe that hangs reports nothing, which is worse than a fast no.

type ProbeResult added in v0.22.0 

type ProbeResult struct {
	// Ready reports whether the endpoint answered 200.
	Ready bool
	// Status is the HTTP status the deployment answered with.
	Status int
	// Detail is the response body, trimmed. Readiness explains its refusal
	// here; liveness has nothing to add beyond "ok".
	Detail string
	// Latency is how long the answer took, which is the number worth watching
	// on readiness: it tracks the database round trip.
	Latency time.Duration
}

ProbeResult is one answer from a deployment probe.

A refused readiness check is a legitimate answer, not a client error, so it arrives here rather than as an error: Ready is false and Status carries the 503. Only a request that never got an answer returns an error.

type ProviderKey 

type ProviderKey = generated.ProviderKey

type ProviderKeyList 

type ProviderKeyList struct {
	HasMore    bool          `json:"has_more"`
	Items      []ProviderKey `json:"items"`
	NextCursor *string       `json:"next_cursor"`
}

type ProviderKeyScope 

type ProviderKeyScope = generated.ProviderKeyScope

type ProviderKeyStatus 

type ProviderKeyStatus = generated.ProviderKeyStatus

type ProviderKeyUsage 

type ProviderKeyUsage = generated.ProviderKeyUsage

type PublishOptions added in v0.30.0 

type PublishOptions struct {
	IdempotencyKey string
}

type ReducedSnapshot 

type ReducedSnapshot struct {
	Messages    []ConversationMessage `json:"messages"`
	TurnChanges []TurnChange          `json:"turn_changes"`
	Previews    []StreamPreview       `json:"previews"`
	Cursor      string                `json:"cursor,omitempty"`
}

type Reducer 

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

Reducer folds replayable durable frames and provisional previews into one current view. Durable frames are idempotent by identity and revision.

func NewReducer 

func NewReducer() *Reducer

func (*Reducer) Apply 

func (r *Reducer) Apply(event StreamEvent) error

func (*Reducer) Settled added in v0.16.0 

func (r *Reducer) Settled(turnID string) bool

func (*Reducer) Snapshot 

func (r *Reducer) Snapshot() ReducedSnapshot

type RegisterAppOptions 

type RegisterAppOptions struct {
	ExternalRef              *string
	DisplayName              *string
	OrgID                    *string
	CallbackTimeoutSeconds   *int64
	BrowserAccess            *BrowserAccess
	DefaultRateLimits        *AppDefaultRateLimits
	MachineConcurrencyLimits *MachineConcurrencyLimits
	CreditPolicy             *CreditPolicy
}

type RegisterOrgOptions added in v0.11.0 

type RegisterOrgOptions struct{ ExternalRef *string }

type RetryPolicy 

type RetryPolicy struct {
	MaxAttempts int
	MinDelay    time.Duration
	MaxDelay    time.Duration
}

type RotateCredentialInput 

type RotateCredentialInput struct {
	OverlapSeconds int
	IdempotencyKey string
}

type RotateProviderKeyInput 

type RotateProviderKeyInput struct {
	APIKey         string
	ExpiresAt      *time.Time
	OverlapSeconds *int
	IdempotencyKey string
}

type SchemaIssue 

type SchemaIssue struct {
	Code    string
	Path    string
	Keyword string
	Message string
}

type StreamEvent 

type StreamEvent struct {
	ID    string          `json:"id,omitempty"`
	Type  string          `json:"type"`
	Data  json.RawMessage `json:"data"`
	Retry time.Duration   `json:"retry,omitempty"`
}

StreamEvent is one decoded SSE frame. Data contains the exact target event JSON, while ID is the durable resume cursor when the frame has one.

type StreamPreview 

type StreamPreview struct {
	TurnID       string `json:"turn_id"`
	Attempt      int64  `json:"attempt"`
	MessageID    string `json:"message_id"`
	ContentIndex int    `json:"content_index"`
	Kind         string `json:"kind"`
	Delta        string `json:"delta"`
	ToolCallID   string `json:"tool_call_id,omitempty"`
	Name         string `json:"name,omitempty"`
}

type SummarizeAdmissionsParams added in v0.15.0 

type SummarizeAdmissionsParams = generated.SummarizeAdmissionsParams

type Tenant added in v0.15.0 

type Tenant = generated.Tenant

type TenantList added in v0.15.0 

type TenantList = generated.TenantList

type Tool 

type Tool struct {
	Name    string
	Handler ToolHandler
}

Tool binds one exact durable tool name to a process-local handler. The tool contract remains part of the AgentRevision or inline Behavior.

type ToolCallMode 

type ToolCallMode = generated.ToolCallMode

type ToolCallStatus 

type ToolCallStatus = generated.ToolCallStatus

type ToolCallSummary added in v0.16.0 

type ToolCallSummary = generated.ToolCallSummary

type ToolDeclaration added in v0.30.0 

type ToolDeclaration = generated.ToolDeclaration

type ToolHandler 

type ToolHandler func(context.Context, any, TurnToolContext) (any, error)

type Trace added in v0.15.0 

type Trace = generated.Trace

type TraceList added in v0.15.0 

type TraceList = generated.TraceList

type Turn added in v0.30.0 

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

Turn is a recovery handle. Constructing it performs no request.

func (*Turn) BindTools added in v0.30.0 

func (t *Turn) BindTools(tools ...Tool) *Turn

func (*Turn) ID added in v0.30.0 

func (t *Turn) ID() string

func (*Turn) IdempotencyKey added in v0.30.0 

func (t *Turn) IdempotencyKey() string

func (*Turn) Result added in v0.30.0 

func (t *Turn) Result(ctx context.Context) (*TurnResult, error)

func (*Turn) Status added in v0.30.0 

func (t *Turn) Status(ctx context.Context) (*TurnSnapshot, error)

func (*Turn) Updates added in v0.30.0 

func (t *Turn) Updates(ctx context.Context, options UpdatesOptions, consume func(TurnUpdate) error) error

Updates follows this Turn as reduced snapshots, reconnecting from the last durable cursor until its terminal change arrives or the consumer stops it with ErrStopStream. Raw SSE frames remain available through Raw().

type TurnAccess added in v0.30.0 

type TurnAccess struct {
	TenantKey string
	UserKey   string
}

type TurnAdmission added in v0.30.0 

type TurnAdmission struct {
	IdempotencyKey string
	Deduplicated   bool
}

type TurnAdmissionError added in v0.30.0 

type TurnAdmissionError struct {
	Base           *Error
	IdempotencyKey string
}

TurnAdmissionError means a transport outcome was uncertain after the SDK had fixed the idempotency key. Repeating the exact admission with that key recovers the same Turn if the service accepted it.

func (*TurnAdmissionError) Error added in v0.30.0 

func (e *TurnAdmissionError) Error() string

func (*TurnAdmissionError) Unwrap added in v0.30.0 

func (e *TurnAdmissionError) Unwrap() error

type TurnChange added in v0.30.0 

type TurnChange = generated.TurnChange

type TurnErasedError added in v0.30.0 

type TurnErasedError struct {
	Base     *Error
	TurnID   string
	ErasedAt *time.Time
}

TurnErasedError reports that a Turn's retained identity and lifecycle facts still exist, but its private content has been erased.

func (*TurnErasedError) Error added in v0.30.0 

func (e *TurnErasedError) Error() string

func (*TurnErasedError) Unwrap added in v0.30.0 

func (e *TurnErasedError) Unwrap() error

type TurnExecutionError added in v0.30.0 

type TurnExecutionError struct {
	Result *TurnResult
}

TurnExecutionError reports a terminal failed or cancelled Turn while retaining its complete result snapshot for diagnostics and recovery.

func (*TurnExecutionError) Error added in v0.30.0 

func (e *TurnExecutionError) Error() string

type TurnInput added in v0.30.0 

type TurnInput = any

TurnInput accepts either a string or []InputBlock. Go cannot express that parameter union while preserving the concise bare-string call, so the facade validates the dynamic value before making a request.

type TurnOptions added in v0.30.0 

type TurnOptions struct {
	TenantKey      string
	UserKey        string
	IdempotencyKey string
	Conversation   *ConversationSelection
	Memory         *MemorySelection
	Limits         *Limits
	Metadata       map[string]string
	Wait           WaitOptions
}

type TurnResource added in v0.30.0 

type TurnResource = generated.Turn

type TurnResult added in v0.30.0 

type TurnResult struct {
	TurnSnapshot
	Turn      *Turn
	Admission *TurnAdmission
}

type TurnResultResource added in v0.30.0 

type TurnResultResource = generated.TurnResult

type TurnSnapshot added in v0.30.0 

type TurnSnapshot struct {
	Resource   TurnResource
	Messages   []ConversationMessage
	OutputText *string
}

type TurnStatus added in v0.30.0 

type TurnStatus = generated.TurnStatus

type TurnStopReason added in v0.30.0 

type TurnStopReason = generated.TurnStopReason

type TurnTimeoutError added in v0.30.0 

type TurnTimeoutError struct {
	Base           *Error
	Turn           *Turn
	IdempotencyKey string
}

TurnTimeoutError is a local timeout, not a request to cancel durable work. Turn is present when admission completed; IdempotencyKey remains available even when admission itself had an uncertain timeout.

func (*TurnTimeoutError) Error added in v0.30.0 

func (e *TurnTimeoutError) Error() string

func (*TurnTimeoutError) Unwrap added in v0.30.0 

func (e *TurnTimeoutError) Unwrap() error

type TurnToolContext added in v0.30.0 

type TurnToolContext struct {
	TurnID     string
	ToolCallID string
}

type TurnUpdate added in v0.30.0 

type TurnUpdate struct {
	Snapshot TurnSnapshot
	Previews []StreamPreview
	Cursor   string
}

TurnUpdate is the high-level reduced view yielded while following one Turn. Previews are provisional deltas; Snapshot.Messages contains durable saved messages and Snapshot becomes authoritative after the final point read.

type UpdateAppOptions added in v0.11.0 

type UpdateAppOptions struct {
	DisplayName                   *string
	OrgID                         *string
	CallbackTimeoutSeconds        *int64
	BrowserAccess                 *BrowserAccess
	ClearBrowserAccess            bool
	AnonymousAccess               *AnonymousAccess
	ClearAnonymousAccess          bool
	DefaultRateLimits             *AppDefaultRateLimits
	ClearDefaultRateLimits        bool
	MachineConcurrencyLimits      *MachineConcurrencyLimits
	ClearMachineConcurrencyLimits bool
	CreditPolicy                  *CreditPolicy
}

type UpdatesOptions added in v0.30.0 

type UpdatesOptions struct {
	Cursor *string
	Deltas *bool
}

type UsageBreakdown added in v0.11.0 

type UsageBreakdown = generated.UsageBreakdown

type UsageInterval added in v0.11.0 

type UsageInterval = generated.UsageInterval

type UsageMetrics added in v0.11.0 

type UsageMetrics = generated.UsageMetrics

type UsageRecords added in v0.11.0 

type UsageRecords = generated.UsageRecords

type UsageTimeseries added in v0.11.0 

type UsageTimeseries = generated.UsageTimeseries

type VerifiedCallback 

type VerifiedCallback struct {
	Envelope   CallbackEnvelope
	RawBody    []byte
	DeliveryID string
	ToolCallID string
	ToolName   string
	KeyID      string
	KeyVersion int64
	Timestamp  time.Time
}

func VerifyCallback 

func VerifyCallback(key []byte, header http.Header, rawBody []byte, now time.Time) (VerifiedCallback, error)

VerifyCallback checks one tool-callback delivery and returns its signed body. The signature scheme is shared with VerifyWebhook; only the checks below, which are about what a callback body must say, are particular to it.

type VerifiedWebhook added in v0.22.0 

type VerifiedWebhook struct {
	Envelope   WebhookEnvelope
	RawBody    []byte
	DeliveryID string
	// Event is read from the signed body. The endpoint URL may carry an
	// unsigned per-event suffix; that belongs in logs, not in a dispatch
	// decision.
	Event          WebhookEvent
	Sequence       int64
	TurnID         string
	ConversationID *string
	KeyID          string
	KeyVersion     int64
	Timestamp      time.Time
}

VerifiedWebhook is one Turn webhook whose signature has been checked.

func VerifyWebhook added in v0.22.0 

func VerifyWebhook(key []byte, header http.Header, rawBody []byte, now time.Time) (VerifiedWebhook, error)

VerifyWebhook checks one Turn webhook delivery and returns its signed body. It shares its signature scheme with VerifyCallback, so a host that receives both implements verification once and dispatches on what the verified body says.

The key is the App's webhook-purpose signing key. Callbacks are signed with the callback-purpose key, so a receiver serving both endpoints holds two keys and must not try either against the other's deliveries.

func (VerifiedWebhook) Supersedes added in v0.22.0 

func (w VerifiedWebhook) Supersedes(appliedSequence int64) bool

Supersedes reports whether this delivery describes a later transition of its Turn than the one already applied.

Delivery is at least once, so the same transition can arrive twice and a redelivery can land after a later one. Keep the highest sequence applied per Turn and fold only what supersedes it; a receiver that applies whichever arrived last rolls its own state backwards. Pass 0 for an Turn nothing has been applied for yet.

This is also the dedup: a repeat carries a sequence already applied, so nothing further is needed to make handling idempotent. Answer it with AcceptWebhook all the same — it was delivered, and asking for redelivery of something already handled only produces the same repeat.

type WaitOptions 

type WaitOptions struct {
	PollInterval time.Duration
}

type WebhookContext added in v0.22.0 

type WebhookContext = generated.TurnWebhookContext

type WebhookDelivery added in v0.22.0 

type WebhookDelivery struct {
	Reply   WebhookReply
	Outcome WebhookOutcome
	// Reason is a stable token for a log line. It is never echoed to nvoken,
	// which ignores webhook bodies.
	Reason   string
	Delivery VerifiedWebhook
	Verified bool
	Cause    error
}

WebhookDelivery is one answered delivery: the reply the host writes, and enough about what happened to log it.

type WebhookEnvelope added in v0.22.0 

type WebhookEnvelope struct {
	Nvoken WebhookContext `json:"nvoken"`
	Turn   WebhookSubject `json:"turn"`
}

WebhookEnvelope is the signed body of one Turn webhook.

It mirrors CallbackEnvelope: everything nvoken asserts sits under Nvoken, and the subject of the delivery sits beside it.

type WebhookEvent 

type WebhookEvent = generated.WebhookEvent

type WebhookEventHandler added in v0.22.0 

type WebhookEventHandler func(ctx context.Context, delivery VerifiedWebhook) error

WebhookEventHandler records one transition. Returning an error asks nvoken to deliver it again, so return one when the receiver could not record it and nil when it did.

type WebhookOutcome added in v0.22.0 

type WebhookOutcome string

WebhookOutcome is what a receiver did with one webhook delivery. 

const (
	WebhookHandled WebhookOutcome = "handled"
	WebhookIgnored WebhookOutcome = "ignored"
	WebhookRefused WebhookOutcome = "refused"
	WebhookFailed  WebhookOutcome = "failed"
)

type WebhookReceiver added in v0.22.0 

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

WebhookReceiver answers a Turn-webhook endpoint. It is the callback receiver's twin — same key table, same reply discipline — because nvoken signs both deliveries the same way.

It is a separate receiver rather than a mode of one, because the two endpoints hold different keys: callbacks are signed with the App's callback-purpose key and webhooks with its webhook-purpose key, and neither may be tried against the other's deliveries. 

no keys configured                        503  an operator error, still fixable inside the retry window
signing identity not held                 401  a real identity failure; redelivery reproduces it
signature, timestamp, or envelope invalid 401  the same bytes fail the same way
no handler for the signed event           200  it was delivered; redelivering finds the same absent handler
handler returned nil                      200  the transition is recorded
handler returned an error                 503  the receiver could not record it, so ask for it again

Ordering stays yours. Delivery is at least once and out of order, so the highest applied sequence per Turn has to be read and written in the same transaction as the state it guards — which is the host's transaction, not one this kit can open. Call VerifiedWebhook.Supersedes inside it. A superseded delivery is still a delivery: record nothing and return nil, so it answers 200.

func NewWebhookReceiver added in v0.22.0 

func NewWebhookReceiver(options WebhookReceiverOptions) (*WebhookReceiver, error)

NewWebhookReceiver builds a receiver, refusing a key table that could only fail later at delivery time.

func (*WebhookReceiver) Handle added in v0.22.0 

func (r *WebhookReceiver) Handle(ctx context.Context, header http.Header, rawBody []byte) WebhookDelivery

Handle answers one delivery. It never returns an error: everything that can go wrong is a status nvoken understands, and the outcome says which.

type WebhookReceiverOptions added in v0.22.0 

type WebhookReceiverOptions struct {
	// Keys is every secret this endpoint accepts. Two entries span a rotation.
	Keys []DeliverySigningKey
	// Events maps the event nvoken signs into the body to its handler.
	Events map[WebhookEvent]WebhookEventHandler
	Now    func() time.Time
}

WebhookReceiverOptions configures a receiver.

type WebhookReply added in v0.22.0 

type WebhookReply struct {
	Status int
}

WebhookReply is the HTTP answer to one webhook delivery. nvoken ignores the response body, so only the status carries meaning, and no answer ever affects the Turn the webhook describes.

func AcceptWebhook added in v0.22.0 

func AcceptWebhook() WebhookReply

AcceptWebhook takes responsibility for the delivery. nvoken will not send it again.

func RetryWebhook added in v0.22.0 

func RetryWebhook() WebhookReply

RetryWebhook asks nvoken to deliver again, for a receiver that could not record the transition right now — its store was unreachable, or it is shedding load. Retries are bounded, so a receiver that answers this forever still ends with a transition nobody recorded; reconcile ended Turns from the exact Turn-list endpoint as a backstop.

type WebhookSubject added in v0.22.0 

type WebhookSubject = generated.TurnWebhookSubject

WebhookSubject is a pointer to the turn, not a projection of it. It carries no transcript content, tool arguments, structured output, usage, provenance, or failure message: read GetTurn or GetTurnResult for anything beyond what is here.

Source Files

View all Source files

Directories

Path Synopsis
examples
quickstart command
Package generated provides primitives to interact with the openapi HTTP API.
 Package generated provides primitives to interact with the openapi HTTP API.

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.