Internal knowledge agent

// lib/tools/searchInternalDocs.ts
import { defineTool } from "@pleach/core";
import { z } from "zod";

const Chunk = z.object({
  chunkId:  z.string(),
  docUrl:   z.string().url(),
  docTitle: z.string(),
  text:     z.string(),
  score:    z.number().min(0).max(1),
});

export const searchInternalDocs = defineTool({
  name: "search_internal_docs",
  description: "Retrieve up to 8 chunks from internal documentation. Always call this before composing an answer.",
  input: z.object({
    query: z.string().min(4),
    topK:  z.number().int().min(1).max(8).default(5),
  }),
  output: z.object({
    chunks:        z.array(Chunk),
    maxScore:      z.number().min(0).max(1),
    queryEmbedded: z.array(z.number()),
  }),
  async handler({ query, topK }) {
    const embedding = await embed(query);
    // Tenant isolation is enforced at the storage/RLS layer (the runtime's
    // `tenantId` scope) — it is NOT threaded through the tool context.
    const chunks    = await vectorStore.search(embedding, { topK });
    return {
      chunks,
      maxScore:      Math.max(0, ...chunks.map(c => c.score)),
      queryEmbedded: embedding,
    };
  },
});

// lib/safety/noChunkNoAnswer.ts
import { defineSafetyPolicy, safetyPolicyId } from "@pleach/core/safety";

export const noChunkNoAnswer = defineSafetyPolicy({
  id:          safetyPolicyId("knowledge-agent.no-chunk-no-answer"),
  version:     "1.0.0",
  enforcement: "refusal",
  scope:       { callClass: "synthesize" },
  content: `
[Retrieval confidence policy]
If the retrieval tool returns no chunks with a
score >= 0.6, do not synthesize an answer.
Reply with the standard template:

  "I don't have enough confidence in the internal
   documentation to answer this. Try rephrasing,
   or ask a human."

Cite the empty-result set as the reason.
  `.trim(),
});

// lib/runtime.ts
import { SessionRuntime, AiSdkProvider, definePleachPlugin, appendPrompt } from "@pleach/core";
import { SupabaseAdapter } from "@pleach/core/sessions";
import { SupabaseSaver }   from "@pleach/core/checkpointing";
import { createOpenRouter } from "@openrouter/ai-sdk-provider";

const openrouter = createOpenRouter({ apiKey: process.env.OPENROUTER_API_KEY! });

const KNOWLEDGE_SYSTEM_PROMPT = `You answer questions about internal documentation.

Rules:
- Always call search_internal_docs before answering.
- Cite each claim with the chunk_id and doc URL it came from.
- If the tool returns no chunks above 0.6 score, say you don't know.`;

export function buildKnowledgeRuntime(req: AuthedRequest) {
  return new SessionRuntime({
    provider:     new AiSdkProvider({
      model:    openrouter("anthropic/claude-sonnet-4-5"),
      maxSteps: 5,
    }),
    storage:      new SupabaseAdapter({ client: supabase }),
    checkpointer: new SupabaseSaver({ client: supabase }),
    plugins:      [definePleachPlugin("knowledge-tools", {
      tools:          [searchInternalDocs],
      safetyPolicies: [noChunkNoAnswer, piiRedaction],
      prompts:        [appendPrompt("knowledge-agent.system", KNOWLEDGE_SYSTEM_PROMPT)],
    })],
    tenantId:     req.tenantId,
    userId:       req.userId,
  });
}

select
  turn_id,
  user_id,
  created_at,
  payload->'output'->'finalText' as answer
from harness_auditable_calls
where call_kind = 'llm'
  and created_at >= now() - interval '7 days'
  and exists (
    select 1
    from harness_auditable_calls t
    where t.turn_id = harness_auditable_calls.turn_id
      and t.call_kind = 'tool'
      and t.tool_name = 'search_internal_docs'
      and t.payload->'output'->'chunks' @> jsonb_build_array(
        jsonb_build_object('docUrl', $1)
      )
  );

import { createReplayRuntime } from "@pleach/replay";

const NEW_SYSTEM_PROMPT = `…revised instructions…`;

const challenger = new SessionRuntime({
  provider:     new AiSdkProvider({
    model:    openrouter("anthropic/claude-sonnet-4-5"),
    maxSteps: 5,
  }),
  storage:      new SupabaseAdapter({ client: supabase }),
  plugins:      [definePleachPlugin("knowledge-tools", {
    tools:          [searchInternalDocs],
    safetyPolicies: [noChunkNoAnswer, piiRedaction],
    prompts:        [appendPrompt("knowledge-agent.system", NEW_SYSTEM_PROMPT)],
  })],
});

const replayRuntime = createReplayRuntime({
  sessionRuntime: challenger,
  tenantId:       req.tenantId,
});

const replay = await replayRuntime.replayTurn({
  chatId:    sessionId,
  tenantId:  req.tenantId,
  messageId: goldenTurnId,
});

// `replay.state` is the reconstructed HydratedHarnessState (typed `unknown`):
// the re-synthesized answer plus the tool calls, whose chunks came from the ledger.
const state = replay.state;
console.log(state);

my-app/
  src/
    pleach/
      runtime.ts                # SessionRuntime + tools + safety + storage
      tools/
        search-internal-docs.ts # defineTool — returns chunks with chunkId + sourceUri
      index/
        client.ts               # the vector / lexical index the tool calls into
        ingest.ts               # offline corpus ingestion (separate process)
      safety/
        no-chunk-no-answer.ts   # defineSafetyPolicy — refuses synthesis without chunk evidence
        pii-redaction.ts        # → /docs/scrubbers
    app/
      api/agents/[id]/route.ts
  qa/
    provenance.sql              # "which chunks did turn T cite?"