@neurocode-ai/core 1.18.8

package/src/system-context/index.ts

@@ -0,0 +1,320 @@
+export * as SystemContext from "./index"
+
+import { Effect, Option, Schema } from "effect"
+
+/**
+ * Models privileged system context as independently refreshable typed sources.
+ *
+ * `Source<A>` describes how to observe, compare, and render one value. `make`
+ * closes over `A`, producing an opaque `SystemContext` that composes uniformly
+ * with contexts built from other value types. Interpreters observe the composed
+ * context once, then produce a durable structured
+ * `Snapshot` alongside the exact model-visible baseline or update text.
+ *
+ * Returning `unavailable` means observation failed temporarily. It differs from
+ * removing a source from the context: refresh preserves the admitted snapshot,
+ * and replacement waits rather than silently constructing an incomplete baseline.
+ *
+ * @module
+ */
+
+/** Stable namespaced identity for one independently refreshable context source. */
+export const Key = Schema.String.check(Schema.isPattern(/^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._/-]*$/)).pipe(
+  Schema.brand("SystemContext.Key"),
+)
+export type Key = typeof Key.Type
+
+/** Indicates that a source could not be observed without treating it as removed. */
+export const unavailable = Symbol.for("@neurocode/SystemContext.Unavailable")
+export type Unavailable = typeof unavailable
+
+/** Defines one typed source before its value type is hidden by `make`. */
+export interface Source<A> {
+  readonly key: Key
+  readonly codec: Schema.Codec<A, Schema.Json, never, never>
+  readonly load: Effect.Effect<A | Unavailable>
+  readonly baseline: (current: A) => string
+  readonly update: (previous: A, current: A) => string
+  readonly removed?: (previous: A) => string
+}
+
+const ContextTypeId: unique symbol = Symbol.for("@neurocode/SystemContext")
+
+/** Opaque carrier for composable system context sources. */
+export interface SystemContext {
+  readonly [ContextTypeId]: ReadonlyArray<PackedSource>
+}
+
+/** Durable comparison state for one admitted source. */
+export const SourceSnapshot = Schema.Struct({
+  value: Schema.Json,
+  removed: Schema.optional(Schema.NonEmptyString),
+})
+export type SourceSnapshot = typeof SourceSnapshot.Type
+
+/** Durable structured comparison state for one active context generation. */
+export const Snapshot = Schema.Record(Key, SourceSnapshot)
+export type Snapshot = Readonly<Record<string, SourceSnapshot>>
+
+export interface Generation {
+  readonly baseline: string
+  readonly snapshot: Snapshot
+}
+
+export interface Updated {
+  readonly _tag: "Updated"
+  readonly text: string
+  readonly snapshot: Snapshot
+}
+
+export interface ReplacementReady {
+  readonly _tag: "ReplacementReady"
+  readonly generation: Generation
+}
+
+export interface ReplacementBlocked {
+  readonly _tag: "ReplacementBlocked"
+}
+
+export type ReplacementResult = ReplacementReady | ReplacementBlocked
+export type ReconcileResult = { readonly _tag: "Unchanged" } | Updated | ReplacementResult
+
+export class InitializationBlocked extends Schema.TaggedErrorClass<InitializationBlocked>()(
+  "SystemContext.InitializationBlocked",
+  { keys: Schema.Array(Key) },
+) {
+  override get message() {
+    return `System context initialization blocked by unavailable sources: ${this.keys.join(", ")}`
+  }
+}
+
+export class DuplicateKeyError extends Schema.TaggedErrorClass<DuplicateKeyError>()("SystemContext.DuplicateKeyError", {
+  key: Key,
+}) {
+  override get message() {
+    return `Duplicate system context key: ${this.key}`
+  }
+}
+
+interface PackedSource {
+  readonly key: Key
+  readonly load: Effect.Effect<Loaded | Unavailable>
+}
+
+interface Loaded {
+  readonly baseline: () => Rendered
+  readonly compare: (previous: Schema.Json) => Compared
+}
+
+interface Rendered {
+  readonly text: string
+  readonly snapshot: SourceSnapshot
+}
+
+type Compared =
+  | { readonly _tag: "Incompatible" }
+  | { readonly _tag: "Unchanged" }
+  | { readonly _tag: "Updated"; readonly render: () => Rendered }
+
+interface AvailableEntry extends Loaded {
+  readonly _tag: "Available"
+  readonly key: Key
+}
+
+interface UnavailableEntry {
+  readonly _tag: "Unavailable"
+  readonly key: Key
+}
+
+type Entry = AvailableEntry | UnavailableEntry
+
+/** The identity context. */
+export const empty = context([])
+
+/** Closes a typed source into a context that composes with differently typed sources. */
+export function make<A>(source: Source<A>): SystemContext {
+  const decode = Schema.decodeUnknownOption(source.codec)
+  const encode = Schema.encodeSync(source.codec)
+  const equivalent = Schema.toEquivalence(source.codec)
+  return context([
+    {
+      key: source.key,
+      load: source.load.pipe(
+        Effect.map((value) => {
+          if (isUnavailable(value)) return value
+          const snapshot = (): SourceSnapshot => ({
+            value: encode(value),
+            ...(source.removed ? { removed: requireText(source.key, "removal", source.removed(value)) } : {}),
+          })
+          return {
+            baseline: (): Rendered => ({
+              text: requireText(source.key, "baseline", source.baseline(value)),
+              snapshot: snapshot(),
+            }),
+            compare: (previous): Compared =>
+              Option.match(decode(previous), {
+                onNone: (): Compared => ({ _tag: "Incompatible" }),
+                onSome: (decoded): Compared =>
+                  equivalent(decoded, value)
+                    ? { _tag: "Unchanged" }
+                    : {
+                        _tag: "Updated",
+                        render: () => ({
+                          text: requireText(source.key, "update", source.update(decoded, value)),
+                          snapshot: snapshot(),
+                        }),
+                      },
+              }),
+          }
+        }),
+      ),
+    },
+  ])
+}
+
+/** Combines contexts in order and rejects duplicate source keys immediately. */
+export function combine(values: ReadonlyArray<SystemContext>): SystemContext {
+  const sources = values.flatMap((value) => value[ContextTypeId])
+  assertUniqueKeys(sources)
+  return context(sources)
+}
+
+const observe = (value: SystemContext) =>
+  Effect.forEach(
+    value[ContextTypeId],
+    (source) =>
+      source.load.pipe(
+        Effect.map(
+          (result): Entry =>
+            result === unavailable
+              ? { _tag: "Unavailable", key: source.key }
+              : { _tag: "Available", key: source.key, ...result },
+        ),
+      ),
+    { concurrency: "unbounded" },
+  )
+
+/** Creates the immutable baseline and durable snapshot for a new generation. */
+export function initialize(value: SystemContext): Effect.Effect<Generation, InitializationBlocked> {
+  return observe(value).pipe(
+    Effect.flatMap((entries) => {
+      const unavailable = entries.flatMap((entry) => (entry._tag === "Unavailable" ? [entry.key] : []))
+      if (unavailable.length > 0) return new InitializationBlocked({ keys: unavailable })
+      return Effect.succeed(initializeObservation(entries))
+    }),
+  )
+}
+
+function initializeObservation(entries: ReadonlyArray<Entry>): Generation {
+  const available = entries.filter((entry): entry is AvailableEntry => entry._tag === "Available")
+  const rendered = available.map((entry) => [entry.key, entry.baseline()] as const)
+  return {
+    baseline: render(rendered.map(([, result]) => result.text)),
+    snapshot: Object.fromEntries(rendered.map(([key, result]) => [key, result.snapshot])),
+  }
+}
+
+/** Reconciles current source values with one active generation. */
+export function reconcile(value: SystemContext, previous: Snapshot): Effect.Effect<ReconcileResult> {
+  return observe(value).pipe(
+    Effect.map((entries): ReconcileResult => {
+      const result = reconcileObservation(entries, previous)
+      if (result._tag === "Unchanged" || result._tag === "Updated") return result
+      return replaceObservation(entries, previous)
+    }),
+  )
+}
+
+function reconcileObservation(
+  entries: ReadonlyArray<Entry>,
+  previous: Snapshot,
+): { readonly _tag: "Unchanged" } | Updated | { readonly _tag: "Replace" } {
+  const keys = new Set(entries.map((entry) => entry.key))
+  const comparisons = new Map<Key, Compared>()
+  for (const entry of entries) {
+    if (entry._tag === "Unavailable") continue
+    const stored = getSnapshot(previous, entry.key)
+    if (!stored) continue
+    const compared = entry.compare(stored.value)
+    if (compared._tag === "Incompatible") return { _tag: "Replace" }
+    comparisons.set(entry.key, compared)
+  }
+  for (const key of Object.keys(previous).sort()) {
+    if (keys.has(Key.make(key))) continue
+    if (previous[key].removed === undefined) return { _tag: "Replace" }
+  }
+
+  const snapshot: Record<string, SourceSnapshot> = {}
+  const updates: string[] = []
+  for (const entry of entries) {
+    const stored = getSnapshot(previous, entry.key)
+    if (entry._tag === "Unavailable") {
+      if (stored) snapshot[entry.key] = stored
+      continue
+    }
+    if (!stored) {
+      const rendered = entry.baseline()
+      updates.push(rendered.text)
+      snapshot[entry.key] = rendered.snapshot
+      continue
+    }
+    const compared = comparisons.get(entry.key)
+    if (!compared || compared._tag === "Incompatible")
+      throw new Error(`Missing comparison for system context source ${entry.key}`)
+    if (compared._tag === "Unchanged") {
+      snapshot[entry.key] = stored
+      continue
+    }
+    const rendered = compared.render()
+    updates.push(rendered.text)
+    snapshot[entry.key] = rendered.snapshot
+  }
+  for (const key of Object.keys(previous).sort()) {
+    if (keys.has(Key.make(key))) continue
+    const removed = previous[key].removed
+    if (removed === undefined) throw new Error(`Missing removal rendering for system context source ${key}`)
+    updates.push(removed)
+  }
+  if (updates.length === 0) return { _tag: "Unchanged" }
+  return { _tag: "Updated", text: render(updates), snapshot }
+}
+
+/** Creates a complete replacement generation or blocks while admitted context is unavailable. */
+export function replace(value: SystemContext, previous: Snapshot): Effect.Effect<ReplacementResult> {
+  return observe(value).pipe(Effect.map((entries) => replaceObservation(entries, previous)))
+}
+
+function replaceObservation(entries: ReadonlyArray<Entry>, previous: Snapshot): ReplacementResult {
+  if (entries.some((entry) => entry._tag === "Unavailable" && getSnapshot(previous, entry.key) !== undefined))
+    return { _tag: "ReplacementBlocked" }
+  return { _tag: "ReplacementReady", generation: initializeObservation(entries) }
+}
+
+function context(sources: ReadonlyArray<PackedSource>): SystemContext {
+  return { [ContextTypeId]: sources }
+}
+
+function render(parts: ReadonlyArray<string>) {
+  return parts.join("\n\n")
+}
+
+function getSnapshot(snapshot: Snapshot, key: Key) {
+  return Object.hasOwn(snapshot, key) ? snapshot[key] : undefined
+}
+
+function isUnavailable(value: unknown): value is Unavailable {
+  return value === unavailable
+}
+
+function requireText(key: Key, kind: string, text: string) {
+  if (text.length === 0) throw new Error(`System context source ${key} rendered an empty ${kind}`)
+  return text
+}
+
+function assertUniqueKeys(sources: ReadonlyArray<PackedSource>) {
+  const keys = new Set<Key>()
+  for (const source of sources) {
+    if (keys.has(source.key)) throw new DuplicateKeyError({ key: source.key })
+    keys.add(source.key)
+  }
+}

package/src/system-context/registry.ts

@@ -0,0 +1,49 @@
+export * as SystemContextRegistry from "./registry"
+
+import { Context, Effect, Layer, Ref, Scope } from "effect"
+import { SystemContext } from "./index"
+import { makeLocationNode } from "../effect/app-node"
+
+export interface Entry {
+  readonly key: SystemContext.Key
+  readonly load: Effect.Effect<SystemContext.SystemContext>
+}
+
+export interface Interface {
+  readonly register: (entry: Entry) => Effect.Effect<void, never, Scope.Scope>
+  readonly load: () => Effect.Effect<SystemContext.SystemContext>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@neurocode/v2/SystemContextRegistry") {}
+
+const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const entries = yield* Ref.make<ReadonlyArray<Entry>>([])
+
+    return Service.of({
+      register: Effect.fn("SystemContextRegistry.register")(function* (entry) {
+        yield* Effect.acquireRelease(
+          Ref.modify(entries, (current) => {
+            if (current.some((item) => item.key === entry.key)) return [false, current]
+            return [true, [...current, entry]]
+          }).pipe(
+            Effect.flatMap((added) =>
+              added ? Effect.void : Effect.die(`Duplicate system context entry key: ${entry.key}`),
+            ),
+            Effect.as(entry),
+          ),
+          (entry) => Ref.update(entries, (current) => current.filter((item) => item !== entry)),
+        )
+      }),
+      load: Effect.fn("SystemContextRegistry.load")(function* () {
+        const current = (yield* Ref.get(entries)).toSorted((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+        return SystemContext.combine(
+          yield* Effect.forEach(current, (entry) => entry.load, { concurrency: "unbounded" }),
+        )
+      }),
+    })
+  }),
+)
+
+export const node = makeLocationNode({ service: Service, layer, deps: [] })

package/src/tool/AGENTS.md

@@ -0,0 +1,59 @@
+# Core Tool Architecture
+
+This folder owns Core's one local tool representation, process and Location registration, effective lookup, and settlement.
+
+## Representations
+
+- `tool.ts` defines the opaque canonical `Tool.make({ description, input, output, execute, toModelOutput })` value. Application tools and shipped built-ins use the same type.
+- `application-tools.ts` stores process-scoped application registrations.
+- `tools.ts` exposes the registration-only `Tools.Service` view used by Location producers.
+- `registry.ts` stores only canonical tools, overlays Location registrations over application registrations, derives definitions, invokes tools, and applies generic output bounding.
+
+Do not add a second executable entry type, registry-owned executor, authorization callback, output-path callback, or legacy normalization path.
+
+## Construction
+
+Tool schemas and projection use `input` and `output` terminology. A tool value is opaque: its codecs, executor, definition derivation, and catalog permission declaration are private runtime details.
+
+Location-scoped built-in layers acquire `PermissionV2.Service` and every other required Location service while the layer is constructed. The executor captures those services. Permission sources are always constructed from the canonical invocation context:
+
+```ts
+const source = {
+  type: "tool" as const,
+  messageID: context.assistantMessageID,
+  callID: context.toolCallID,
+}
+```
+
+Leaves own resolution, permission, and side-effect ordering. Translate only expected typed errors into `ToolFailure`; do not use `catchCause`, because interruption and defects must survive.
+
+## Registration
+
+Built-ins register through `Tools.Service.register({ [name]: tool })`. Application tools register through `ApplicationTools.Service.register(...)`, exposed publicly as `neurocode.tools.register(...)`.
+
+Both are scoped:
+
+- The latest active same-placement registration wins.
+- Closing any registration removes only that registration and reveals the next active one.
+- Location registrations take precedence over application registrations.
+- An invocation captures the effective tool once settlement starts.
+
+`ApplicationTools.Service` is process-scoped and shared by all Locations. `ToolRegistry.Service` is Location-scoped. Do not make the registry process-global or construct a separate application-tool service for each Location.
+
+## Permissions
+
+The registry has no `PermissionV2.Service` dependency and performs no execution authorization. An internal built-in-only operation attaches a permission action solely to preserve whole-tool definition filtering; it is not part of public `Tool.make`. Most tools default to their registered name; `edit`, `write`, and `apply_patch` declare the shared `edit` action.
+
+Definition filtering is catalog visibility, not execution authorization. A call still executes the captured leaf policy if it reaches settlement.
+
+## Output
+
+Built-ins return complete validated domain output. `ToolRegistry.Materialization.settle` is the only execution and generic model-output bounding boundary and owns managed retention paths.
+
+Producer capture limits are separate. For example, Bash keeps `AppProcess.maxOutputBytes` and accurately reports stdout/stderr capture loss, but it does not run model-output truncation or return a managed `outputPath`.
+
+## Current Gaps
+
+- Plugin boot has not been redesigned to register canonical tools through `Tools.Service`; do not redesign it as part of leaf migrations.
+- MCP and future Session-scoped registrations still need an explicit canonical registration design.
+- The public Session result shape currently exposes managed `outputPaths`; full storage encapsulation requires a future opaque managed-output reference design.

package/src/tool/application-tools.ts

@@ -0,0 +1,57 @@
+export * as ApplicationTools from "./application-tools"
+
+import { Context, Effect, Layer, Scope } from "effect"
+import { State } from "../state"
+import { Tool } from "./tool"
+import { makeGlobalNode } from "../effect/app-node"
+
+type Data = {
+  readonly entries: Map<string, Entry>
+}
+
+type Draft = {
+  readonly set: (name: string, entry: Entry) => void
+}
+
+export interface Entry {
+  readonly identity: object
+  readonly tool: Tool.AnyTool
+}
+
+export interface Interface {
+  readonly register: (
+    tools: Readonly<Record<string, Tool.AnyTool>>,
+  ) => Effect.Effect<void, Tool.RegistrationError, Scope.Scope>
+  readonly entries: () => ReadonlyMap<string, Entry>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@neurocode/ApplicationTools") {}
+
+const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const state = State.create<Data, Draft>({
+      initial: () => ({ entries: new Map() }),
+      draft: (draft) => ({
+        set: (name, tool) => {
+          draft.entries.set(name, tool)
+        },
+      }),
+    })
+
+    return Service.of({
+      register: Effect.fn("ApplicationTools.register")(function* (tools) {
+        const entries = Object.entries(tools)
+        if (entries.length === 0) return
+        yield* Effect.forEach(entries, ([name]) => Tool.validateName(name), { discard: true })
+        const registrations = entries.map(([name, tool]) => [name, { identity: {}, tool }] as const)
+        yield* state.transform((draft) => {
+          for (const [name, entry] of registrations) draft.set(name, entry)
+        })
+      }),
+      entries: () => state.get().entries,
+    })
+  }),
+)
+
+export const node = makeGlobalNode({ service: Service, layer, deps: [] })