@pi-in-go/pigpen-pi-typesafe 0.1.0

package/extensions/pi-typesafe/review_test.go

@@ -0,0 +1,134 @@
+package pi_typesafe_test
+
+import (
+	"strings"
+	"sync"
+	"testing"
+
+	pi_typesafe "github.com/MichaelKinsy/pigpen/components/pi-typesafe/extensions/pi-typesafe"
+)
+
+// Cases added by the review (rev-pigpen-typesafe).
+
+// Consent is per destination. A /typesafe backend switch may arrive while a tool call is running (PiG runs
+// extension commands during a turn); the call that was admitted under the TypeSafe consent must not be sent
+// to the own model, whose destination the operator has not consented to. It stops and says so.
+func TestBackendSwitchAfterAdmissionKeepsTheConsentedDestination(t *testing.T) {
+	own := &fakeOwn{}
+	r := newRig(t, func(o *pi_typesafe.Options) { o.Evaluator = own })
+	t.Setenv("TYPESAFE_API_KEY", "offline-test-key")
+	t.Setenv("PI_TYPESAFE_ENABLED", "1")
+	r.startSession("startup")
+	var once sync.Once
+	var switchFailure string
+	restore := pi_typesafe.SetAdmittedHook(func() {
+		once.Do(func() { switchFailure = r.host.Command("typesafe", "backend ownmodel") })
+	})
+	defer restore()
+	_, failure := r.tool(nil)
+	if switchFailure != "" {
+		t.Fatalf("switch: %s", switchFailure)
+	}
+	if own.calls != 0 {
+		t.Fatalf("an admitted TypeSafe call reached the own model, a destination nobody consented to (calls=%d)", own.calls)
+	}
+	if !strings.Contains(failure, "nothing was sent") || r.network.Load() != 0 {
+		t.Fatalf("the call stops and says so: failure=%q network=%d", failure, r.network.Load())
+	}
+	if _, failure := r.tool(nil); !strings.Contains(failure, "disabled") || own.calls != 0 {
+		t.Fatalf("after the switch the tool is disabled: %q calls=%d", failure, own.calls)
+	}
+}
+
+// The same for /typesafe test: the operator confirmed sending to api.typesafe.ai; if the backend changed while
+// the dialog was open, nothing is sent.
+func TestSampleSendsNothingWhenTheBackendChangedDuringConsent(t *testing.T) {
+	own := &fakeOwn{}
+	r := newRig(t, func(o *pi_typesafe.Options) { o.Evaluator = own })
+	t.Setenv("TYPESAFE_API_KEY", "offline-test-key")
+	var once sync.Once
+	r.onConfirm = func() { once.Do(func() { _ = r.host.Command("typesafe", "backend ownmodel") }) }
+	r.command("test")
+	if !strings.Contains(r.confirmBodies[0], "api.typesafe.ai") {
+		t.Fatalf("consent body = %s", r.confirmBodies[0])
+	}
+	if own.calls != 0 || r.network.Load() != 0 || len(r.entries) != 0 {
+		t.Fatalf("nothing may be sent after the destination changed: own=%d network=%d entries=%d", own.calls, r.network.Load(), len(r.entries))
+	}
+	if !strings.Contains(r.lastNotice(), "nothing was sent") {
+		t.Fatalf("the operator is told: %s", r.lastNotice())
+	}
+}
+
+// The original reads the whole argument text as the action (`args.trim() || "status"`), so an action with
+// trailing words is not an action: it gets the usage text, and nothing runs. Only this port's `backend`
+// takes an argument.
+func TestAnActionWithTrailingWordsGetsTheUsageText(t *testing.T) {
+	r := newRig(t)
+	t.Setenv("TYPESAFE_API_KEY", "offline-test-key")
+	for _, args := range []string{"status now", "enable yes", "disable all", "logout please", "test twice"} {
+		r.command(args)
+		if !strings.HasPrefix(r.lastNotice(), "Usage: /typesafe login | logout") {
+			t.Fatalf("/typesafe %s: %s", args, r.lastNotice())
+		}
+	}
+	if r.confirmations != 0 || r.network.Load() != 0 {
+		t.Fatalf("nothing runs: confirmations=%d network=%d", r.confirmations, r.network.Load())
+	}
+	r.command("  status  ")
+	if !strings.HasPrefix(r.lastNotice(), "TypeSafe: disabled.") {
+		t.Fatalf("surrounding space is trimmed: %s", r.lastNotice())
+	}
+	r.command("backend ownmodel")
+	if !strings.Contains(r.lastNotice(), "Backend set to ownmodel") {
+		t.Fatalf("backend takes its argument: %s", r.lastNotice())
+	}
+}
+
+// Off by default: only the exact value 1 enables the tool from the environment, at construction and at
+// every session start, as in the original (`process.env.PI_TYPESAFE_ENABLED === "1"`).
+func TestOnlyTheExactValueOneEnablesFromTheEnvironment(t *testing.T) {
+	for _, value := range []string{"0", "true", "yes", " 1", "1 "} {
+		r := newRig(t, func(*pi_typesafe.Options) { t.Setenv("PI_TYPESAFE_ENABLED", value) })
+		t.Setenv("TYPESAFE_API_KEY", "offline-test-key")
+		if _, failure := r.tool(nil); !strings.Contains(failure, "TypeSafe is disabled") {
+			t.Fatalf("PI_TYPESAFE_ENABLED=%q at load enabled the tool: %q", value, failure)
+		}
+		r.startSession("reload")
+		if _, failure := r.tool(nil); !strings.Contains(failure, "TypeSafe is disabled") {
+			t.Fatalf("PI_TYPESAFE_ENABLED=%q at session start enabled the tool: %q", value, failure)
+		}
+		if r.network.Load() != 0 {
+			t.Fatalf("PI_TYPESAFE_ENABLED=%q sent a request", value)
+		}
+	}
+	r := newRig(t, func(*pi_typesafe.Options) { t.Setenv("PI_TYPESAFE_ENABLED", "1") })
+	t.Setenv("TYPESAFE_API_KEY", "offline-test-key")
+	if _, failure := r.tool(nil); failure != "" || r.network.Load() != 1 {
+		t.Fatalf("PI_TYPESAFE_ENABLED=1 enables: %q network=%d", failure, r.network.Load())
+	}
+}
+
+// The production own-model evaluator (hostmodel), not an injected one: with no model selected in PiG the
+// call fails with the reason (not a generic "unreadable response"), the callout does not blame a key the
+// backend does not use, and nothing is sent anywhere; status names the configured model.
+func TestOwnModelBackendOnTheHostModel(t *testing.T) {
+	r := newRig(t, func(*pi_typesafe.Options) {
+		t.Setenv("PI_TYPESAFE_BACKEND", "ownmodel")
+		t.Setenv("PI_TYPESAFE_ENABLED", "1")
+	})
+	before := r.noticeCount()
+	_, failure := r.tool(nil)
+	if !strings.Contains(failure, "No model is configured in PiG; select one with /model first.") || r.network.Load() != 0 || r.modelList.Load() != 0 {
+		t.Fatalf("failure=%q network=%d", failure, r.network.Load())
+	}
+	said := strings.Join(r.noticesSince(before), "\n")
+	if !strings.Contains(said, "No model is configured in PiG") || strings.Contains(said, "key") || strings.Contains(said, "not authenticated") {
+		t.Fatalf("callout = %q", said)
+	}
+	r.modelInfo = map[string]any{"id": "model-one", "provider": "provider-one", "name": "Model One"}
+	r.command("status")
+	if !strings.Contains(r.lastNotice(), "Model: provider-one/model-one.") || !strings.Contains(r.lastNotice(), "Nothing is sent to api.typesafe.ai") {
+		t.Fatalf("status = %s", r.lastNotice())
+	}
+}

package/extensions/pi-typesafe/tool.go

@@ -0,0 +1,193 @@
+package pi_typesafe
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	sdk "github.com/MichaelKinsy/PiG/extensions/sdk"
+	pitypesafe "github.com/MichaelKinsy/pigpen/components/pi-typesafe-api"
+)
+
+const ownModelMsg = "Submitted state and questions will be sent to the provider of the model PiG is configured with (the own-model backend) and may incur charges there. Nothing is sent to api.typesafe.ai. Do not include secrets. The extension does not collect files or conversation history. Results are model judgments, not proof or authorization."
+
+// disclosure says where submitted content goes for a backend.
+func disclosure(backend string) string {
+	if backend == pitypesafe.BackendOwnModel {
+		return ownModelMsg
+	}
+	return typesafeMsg
+}
+
+// sampleJSON is the request the playground edits and the tool guidelines show: the payload shape is what models get
+// wrong on the first call, and it is paid for on every tool listing, so it stays short.
+const sampleJSON = `{"state":{"message":"I was charged twice for my subscription. Please help today."},"questions":{` +
+	`"category":{"type":"choice","instructions":"Which team should handle this message?","criteria":{"billing":"Charges and payments","technical":"Software failures","other":"None of these"}},` +
+	`"urgent":{"type":"noul","instructions":"Does the sender request help today?"},` +
+	`"frustration":{"type":"score","instructions":"How frustrated does the sender sound?","criteria":["Neutral request","Frustrated but civil","Angry or threatening"]}}}`
+
+func toolDescription(backend string) string {
+	return "Evaluate supplied state with independent Choice, Score, and Noul questions in one TypeSafe request. " +
+		"Each question judges the whole state, so when several items are involved, put each item in a named state field (e.g. `reports.r1`) and ask one question per item per dimension (e.g. `r1_owner`, `r2_owner`), naming the field in the instructions; never aggregate several items into one question. " +
+		disclosure(backend) + " Requires operator opt-in via /typesafe enable or PI_TYPESAFE_ENABLED=1. " +
+		fmt.Sprintf("Limit: 32 questions, %d KiB JSON, %d attempts per session; no retries.", pitypesafe.DefaultMaxInputBytes/1024, pitypesafe.DefaultMaxRequests)
+}
+
+func toolGuidelines() []string {
+	return []string{
+		// The payload shape is what models get wrong on the first call; the same sample the playground edits is the cheapest way to show it.
+		"Request shape, all three question kinds in one call: " + sampleJSON,
+		"Use typesafe_evaluate only for requested semantic judgments, not calculations or exact lookups; send only the relevant permitted data.",
+		"Batch independent typesafe_evaluate questions over the same state; use code or explicit permission rules for actions, never confidence as authorization.",
+		"When typesafe_evaluate judges several items, give each item a named state field and ask one question per item per dimension, naming the field in the instructions; one question over many items returns an unusable blend.",
+		"Report typesafe_evaluate answers as the model's judgments with their probabilities; do not replace them with your own guesses, and say when an answer is uncertain.",
+	}
+}
+
+// toMap converts an ordered tree into the maps the SDK's arguments use.
+func toMap(v any) any {
+	switch t := v.(type) {
+	case *pitypesafe.Object:
+		m := make(map[string]any, t.Len())
+		for _, k := range t.Keys() {
+			x, _ := t.Get(k)
+			m[k] = toMap(x)
+		}
+		return m
+	case []any:
+		out := make([]any, len(t))
+		for i, e := range t {
+			out[i] = toMap(e)
+		}
+		return out
+	}
+	return v
+}
+
+// registerTool (re)registers typesafe_evaluate; registering a name again replaces the definition, which is how
+// a backend switch updates the disclosure in the tool description.
+func (s *state) registerTool() {
+	backend := s.currentBackend()
+	s.ext.RegisterTool(sdk.ToolDefinition{
+		Name:             toolName,
+		Label:            "TypeSafe",
+		Description:      toolDescription(backend),
+		PromptSnippet:    "Ask batched structured questions with TypeSafe (external service; operator opt-in required)",
+		PromptGuidelines: toolGuidelines(),
+		Parameters:       pitypesafe.EvaluationSchema(),
+		// Pi validates against `parameters` after this hook.
+		PrepareArguments: func(params map[string]any) (map[string]any, error) {
+			if normalized, ok := toMap(pitypesafe.NormalizeEvaluationRequest(params)).(map[string]any); ok {
+				return normalized, nil
+			}
+			return params, nil
+		},
+		Execute:      s.execute,
+		RenderCall:   s.renderCall,
+		RenderResult: s.renderResult,
+	})
+}
+
+// admitted is a test seam (export_test.go): it runs after a tool call passed the consent gate and before
+// anything is sent, where a concurrent /typesafe command could change the backend.
+var admitted = func() {}
+
+func (s *state) execute(ctx sdk.Context, params map[string]any) (any, error) {
+	enabled, consent := s.admit()
+	if !enabled {
+		return nil, &pitypesafe.IntegrationError{Code: pitypesafe.CodeConfiguration, Message: "TypeSafe is disabled. Ask the operator to run /typesafe enable; do not enable it by editing configuration or environment files."}
+	}
+	admitted()
+	// The tool admits through the same rule as the library; EvaluateRaw re-runs it idempotently.
+	request, err := pitypesafe.PrepareEvaluationRequest(params, pitypesafe.PrepareOptions{})
+	if err != nil {
+		return nil, err
+	}
+	client, err := s.clientFor(consent)
+	if err == errDestinationChanged {
+		return nil, err
+	}
+	if err != nil {
+		return nil, s.report(ctx, err)
+	}
+	goCtx, cancel := goContext(ctx)
+	defer cancel()
+	result, err := client.EvaluateRaw(goCtx, request)
+	if err != nil {
+		return nil, s.report(ctx, err)
+	}
+	content, err := result.MarshalJSON()
+	if err != nil {
+		return nil, err
+	}
+	details, err := result.DetailsJSON()
+	if err != nil {
+		return nil, err
+	}
+	return sdk.ToolResult{Content: string(content), Details: json.RawMessage(details)}, nil
+}
+
+// report classifies a failure and, when it means every later judgment is skipped, calls it out once.
+func (s *state) report(ctx sdk.Context, err error) error {
+	safe := pitypesafe.SafeError(err, s.currentBackend())
+	// Authentication degradation is louder than a single failed call: it means every later judgment is skipped.
+	rejected := safe.Code == pitypesafe.CodeHTTP && (safe.Status == 401 || safe.Status == 403)
+	if rejected || safe.Code == pitypesafe.CodeConfiguration {
+		status := ""
+		if safe.Status != 0 {
+			status = fmt.Sprint(safe.Status)
+		}
+		text := "TypeSafe is not authenticated (" + safe.Message + ") Judgments will fail until the key is fixed."
+		if s.currentBackend() == pitypesafe.BackendOwnModel {
+			// The own-model backend has no key of this extension: name what failed instead.
+			text = "The own-model backend cannot answer (" + safe.Message + ") Judgments will fail until this is fixed."
+		}
+		s.callOut(ctx, "run:"+string(safe.Code)+":"+status, text)
+	}
+	return safe
+}
+
+func (s *state) renderCall(_ sdk.Context, args map[string]any, _ sdk.ToolRenderContext, width int) ([]string, error) {
+	questions, _ := args["questions"].(map[string]any)
+	where := "external request"
+	if s.currentBackend() == pitypesafe.BackendOwnModel {
+		where = "configured model"
+	}
+	return wrapText(fmt.Sprintf("TypeSafe · %d questions · %s", len(questions), where), width), nil
+}
+
+func (s *state) renderResult(_ sdk.Context, result sdk.ToolRenderResult, opts sdk.ToolRenderResultOptions, _ sdk.ToolRenderContext, width int) ([]string, error) {
+	if opts.IsPartial {
+		return wrapText("TypeSafe · waiting for response", width), nil
+	}
+	details, _ := result.Details.(map[string]any)
+	if _, ok := details["answers"].(map[string]any); !ok {
+		var parts []string
+		for _, block := range result.Content {
+			if block["type"] == "text" {
+				text, _ := block["text"].(string)
+				parts = append(parts, text)
+			}
+		}
+		return wrapText(strings.Join(parts, "\n"), width), nil
+	}
+	return wrapText(format(details, opts.Expanded), width), nil
+}
+
+func (s *state) renderEntry(_ sdk.Context, entry map[string]any, opts sdk.EntryRenderOptions, width int) ([]string, error) {
+	data, _ := entry["data"].(map[string]any)
+	if data == nil {
+		return wrapText("TypeSafe · no result", width), nil
+	}
+	return wrapText(format(data, opts.Expanded), width), nil
+}
+
+// ToolDescription is the typesafe_evaluate description for a backend: the original's text, with the own-model
+// disclosure when that backend is selected.
+func ToolDescription(backend string) string { return toolDescription(backend) }
+
+// ToolGuidelines are the prompt guidelines of typesafe_evaluate, the request-shape example first.
+func ToolGuidelines() []string { return toolGuidelines() }
+
+// Disclosure says where submitted content goes for a backend.
+func Disclosure(backend string) string { return disclosure(backend) }

package/extensions/pi-typesafe/twin_test.go

@@ -0,0 +1,28 @@
+package pi_typesafe_test
+
+// Twin helpers for a port whose original has tests. Every upstream test case gets one
+// tw(...) call carrying the upstream title unchanged, or one tskip(...) with the reason it
+// cannot be ported. `pigeq twins check` reads these calls and fails on a missing title, an
+// unknown one (a misspelling) or one reason shared by many skips.
+//
+//	pigeq twins list --tests <upstream>/test > port/upstream-tests.json
+//	pigeq twins check --ledger port/upstream-tests.json --go extensions/<name> [--files a,b]
+//
+// Copy this file into the port as twin_test.go and replace pi_typesafe_test with the package name (in
+// an external test package use `pi_typesafe_test_test`). A parametrized upstream title (it contains
+// `${`) is twinned once, with the template text unchanged.
+
+import "testing"
+
+// tw runs one exact twin: file is the upstream test file (its name without .test.mjs), title
+// the upstream test title, unchanged.
+func tw(t *testing.T, file, title string, fn func(t *testing.T)) {
+	t.Helper()
+	t.Run(title, fn)
+}
+
+// tskip records a named gap: the upstream case has no Go twin, with its own reason.
+func tskip(t *testing.T, file, title, reason string) {
+	t.Helper()
+	t.Run(title, func(t *testing.T) { t.Skip(reason) })
+}

package/libs/pi-typesafe-api/CREDITS.md

@@ -0,0 +1,14 @@
+# Credits
+
+This Package is a Go port of **pi-typesafe** 0.8.0, https://github.com/DevMortimer/pi-typesafe, by
+**Ryan Gapac** (MIT, Copyright (c) 2026 Ryan Gapac). It is an independent project, not affiliated with TypeSafe AI or
+the Pi authors, and so is this port.
+
+- Pinned commit: `ed439f834665ad6fc652787f5ba7c23852566d49` (release 0.8.0, "Add Command Code backend and caller-supplied endpoints")
+- The unmodified original, with its tests, is vendored in `components/pi-typesafe/port/oracle/`; its license is in `LICENSE`
+  of this Package and in `components/pi-typesafe/port/oracle/LICENSE`.
+- What is modified: everything. The behavior, wording and structure follow the original; the code is a Go
+  implementation over the shared TypeSafe client (`components/typesafe`, a port of the official `@typesafe-ai/sdk`).
+  The mapping from each original file to its Go file is in `components/pi-typesafe/port/PORT.md`, with every deliberate difference.
+
+The Go code, scenarios and tests were written for Pigpen by Michael Kinsy.

package/libs/pi-typesafe-api/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Ryan Gapac
+Copyright (c) 2026 Michael Kinsy (the Go port)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/libs/pi-typesafe-api/README.md

@@ -0,0 +1,30 @@
+# pi-typesafe-api (typed Go API)
+
+The library half of the [pi-typesafe](../pi-typesafe/README.md) port: what an extension author imports to ask Jev typed
+questions safely. Go module `github.com/MichaelKinsy/pigpen/components/pi-typesafe-api`, package `pitypesafe`, over the shared
+client `components/typesafe`. A consumer extension's `go.mod` requires it at `v0.0.0` (no `replace`) and its directory has a
+`go.work` with `use ( . ../../../pi-typesafe-api ../../../typesafe )`.
+
+```go
+client, err := pitypesafe.New(pitypesafe.Options{MaxRequests: 5, MaxUSDPerDay: 1}) // key: TYPESAFE_API_KEY, else the login store
+answer := pitypesafe.Ask(ctx, client, typesafe.SystemOneRequest{
+	State: typesafe.Text("I was charged twice."),
+	Questions: typesafe.Questions{typesafe.Ask("billing", typesafe.Noul("Is this about billing?"))},
+}, pitypesafe.AskOptions{Timeout: 5 * time.Second})
+if !answer.OK { /* answer.ErrorCode == pitypesafe.CodeBudget: stop asking; never an error value */ }
+```
+
+| Piece | Where |
+|---|---|
+| Admission (`PrepareEvaluationRequest`: normalize model near-misses, validate, byte budget), `EvaluationSchema` | `schema.go`, `evaluation_schema.json` |
+| Client with request budget, day caps, ledger, auth recording (`New`, `Evaluate`, `EvaluateRaw`, `ListModels`, `GetSpend`) | `client.go`, `usage.go`, `auth.go` |
+| Backends: `typesafe`, `openrouter`, `commandcode`, a caller-supplied endpoint, and `ownmodel` | `backends.go` |
+| Key store, key situations, `AgentDir` (PiG's directory) | `credentials.go` |
+| `Ask`, `EvaluateMany`, `EvaluateAll`, `ChunkRequest`, `FanOut` | `ask.go`, `batch.go` |
+| Calibration kit (`Calibrate`, `Replay`, `AUC`, ...) | `calibrate.go` |
+| Own model on the PiG SDK's model access | `hostmodel/` |
+| Hidden-input key prompt, `LoginWithPrompt`, `EnsureAPIKey` | `ui/` |
+
+**Where content goes.** TypeSafe, OpenRouter, Command Code and custom-endpoint backends send it to that host
+(`BackendHost` names it for consent text); the `ownmodel` backend sends it to the provider of the model PiG is configured with. A
+key for one backend is never sent to another. Credit and license: [CREDITS.md](CREDITS.md). Mapping: [port/PORT.md](port/PORT.md).

package/libs/pi-typesafe-api/ask.go

@@ -0,0 +1,62 @@
+package pitypesafe
+
+import (
+	"context"
+	"time"
+
+	"github.com/MichaelKinsy/pigpen/components/typesafe/libraries/typesafe"
+)
+
+// Judge is anything with a client's Evaluate: the real client in a session, a stub in tests.
+type Judge interface {
+	Evaluate(ctx context.Context, request typesafe.SystemOneRequest) (*Evaluation, error)
+}
+
+// DefaultAskTimeout is the default per-ask deadline; it matches the client's own request timeout.
+const DefaultAskTimeout = 15 * time.Second
+
+const askFallbackMessage = "TypeSafe request failed."
+
+// AskOptions configure Ask.
+type AskOptions struct {
+	// Timeout is the per-ask deadline, merged with the caller's own context. Default: DefaultAskTimeout.
+	Timeout time.Duration
+}
+
+// AskAnswer is the outcome of Ask.
+type AskAnswer struct {
+	OK bool
+	// The fields below are set when OK.
+	Answers   map[string]typesafe.Answer
+	Order     []string
+	Model     string
+	Usage     typesafe.Usage
+	ElapsedMs int64
+	// Error and ErrorCode are set when not OK; ErrorCode is empty for a failure that is not an IntegrationError.
+	Error     string
+	ErrorCode ErrorCode
+}
+
+// Ask is one typed Jev request that never fails: a failure comes back as an AskAnswer with OK false, this
+// package's own message (which carries no upstream body, header, key, or submitted state) and its code, so a
+// caller can stop asking after a budget error. The per-ask timeout is merged into the caller's context, so
+// either can cancel the request.
+//
+// This is the author-facing "ask Jev" seam. Agents get the same admission through the typesafe_evaluate tool;
+// the two share PrepareEvaluationRequest, so what one accepts the other accepts.
+func Ask(ctx context.Context, judge Judge, request typesafe.SystemOneRequest, opts AskOptions) AskAnswer {
+	timeout := opts.Timeout
+	if timeout <= 0 {
+		timeout = DefaultAskTimeout
+	}
+	ctx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+	result, err := judge.Evaluate(ctx, request)
+	if err != nil {
+		if ie, ok := err.(*IntegrationError); ok {
+			return AskAnswer{Error: ie.Message, ErrorCode: ie.Code}
+		}
+		return AskAnswer{Error: askFallbackMessage}
+	}
+	return AskAnswer{OK: true, Answers: result.Answers, Order: result.Order, Model: result.Model, Usage: result.Usage, ElapsedMs: result.ElapsedMs}
+}

package/libs/pi-typesafe-api/ask_test.go

@@ -0,0 +1,76 @@
+package pitypesafe
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"reflect"
+	"testing"
+	"time"
+
+	"github.com/MichaelKinsy/pigpen/components/typesafe/libraries/typesafe"
+)
+
+type judgeFunc func(ctx context.Context, r typesafe.SystemOneRequest) (*Evaluation, error)
+
+func (f judgeFunc) Evaluate(ctx context.Context, r typesafe.SystemOneRequest) (*Evaluation, error) {
+	return f(ctx, r)
+}
+
+func TestAsk(t *testing.T) {
+	tw(t, "ask", "a successful ask returns the typed answers, model, usage, and duration", func(t *testing.T) {
+		judge := judgeFunc(func(context.Context, typesafe.SystemOneRequest) (*Evaluation, error) {
+			return &Evaluation{SystemOneResult: &typesafe.SystemOneResult{Model: "jev-test", Answers: map[string]typesafe.Answer{"yes": typesafe.NoulAnswer{Noul: 0.9}}, Usage: typesafe.Usage{InputTokens: 12}}, ElapsedMs: 7, Order: []string{"yes"}}, nil
+		})
+		a := Ask(context.Background(), judge, sampleRequest(), AskOptions{})
+		yes, _ := a.Answers["yes"].(typesafe.NoulAnswer)
+		if !a.OK || yes.Noul != 0.9 || a.Model != "jev-test" || a.Usage.InputTokens != 12 || a.ElapsedMs != 7 {
+			t.Fatalf("answer = %+v", a)
+		}
+	})
+	tw(t, "ask", "a typed failure comes back as data, with pi-typesafe's own code and message", func(t *testing.T) {
+		fail := func(err error) Judge {
+			return judgeFunc(func(context.Context, typesafe.SystemOneRequest) (*Evaluation, error) { return nil, err })
+		}
+		budget := Ask(context.Background(), fail(newError(CodeBudget, "TypeSafe request limit reached (1 attempts per client instance).")), sampleRequest(), AskOptions{})
+		if !reflect.DeepEqual(budget, AskAnswer{Error: "TypeSafe request limit reached (1 attempts per client instance).", ErrorCode: CodeBudget}) {
+			t.Fatalf("budget = %+v", budget)
+		}
+		e := &IntegrationError{Code: CodeHTTP, Message: "TypeSafe returned HTTP 401. Check TYPESAFE_API_KEY. No automatic retry was made.", Status: 401}
+		if h := Ask(context.Background(), fail(e), sampleRequest(), AskOptions{}); h.OK || h.ErrorCode != CodeHTTP {
+			t.Fatalf("http = %+v", h)
+		}
+	})
+	tw(t, "ask", "an unknown failure is replaced by a fixed message so nothing from the transport escapes", func(t *testing.T) {
+		judge := judgeFunc(func(context.Context, typesafe.SystemOneRequest) (*Evaluation, error) {
+			return nil, errors.New("upstream body with a key: sk-secret")
+		})
+		a := Ask(context.Background(), judge, sampleRequest(), AskOptions{})
+		if !reflect.DeepEqual(a, AskAnswer{Error: "TypeSafe request failed."}) {
+			t.Fatalf("answer = %+v", a)
+		}
+		if data, _ := json.Marshal(a); contains(string(data), "sk-secret") {
+			t.Fatal("secret escaped")
+		}
+	})
+	tw(t, "ask", "the ask deadline and the caller's signal both cancel the request", func(t *testing.T) {
+		slow := judgeFunc(func(ctx context.Context, _ typesafe.SystemOneRequest) (*Evaluation, error) {
+			<-ctx.Done()
+			return nil, newError(CodeAborted, "TypeSafe request cancelled before submission.")
+		})
+		timedOut := Ask(context.Background(), slow, sampleRequest(), AskOptions{Timeout: 5 * time.Millisecond})
+		if !reflect.DeepEqual(timedOut, AskAnswer{Error: "TypeSafe request cancelled before submission.", ErrorCode: CodeAborted}) {
+			t.Fatalf("timed out = %+v", timedOut)
+		}
+		ctx, cancel := context.WithCancel(context.Background())
+		done := make(chan AskAnswer, 1)
+		go func() { done <- Ask(ctx, slow, sampleRequest(), AskOptions{Timeout: 5 * time.Second}) }()
+		cancel()
+		if a := <-done; a.OK {
+			t.Fatal("a cancelled ask must fail")
+		}
+		if DefaultAskTimeout != 15*time.Second {
+			t.Errorf("default = %v", DefaultAskTimeout)
+		}
+	})
+}