"""Read Intelligence metadata first, then one file, and submit edits for approval.""" from functools import wraps from core.external_tools import ToolContext from deps import err import intelligence_store as files def _handler(action, allowed, required=()): def decorate(fn): @wraps(fn) def call(ctx, args): if not isinstance(ctx, ToolContext): raise err(403, "tool_context_required", "Use the authenticated Brain tool.") if (not isinstance(args, dict) or set(args) - set(allowed) - {"action"} or set(required) - set(args) or args.get("action", action) != action): raise err(400, "bad_arguments", f"Use only the declared arguments for intelligence.{action}.") try: return fn(ctx, args) except files.IntelligenceError as exc: raise err(exc.status, exc.code, str(exc)) from None return call return decorate @_handler("index", ()) def index(ctx, args): """Read section counts and your visible pins in at most 4 KB, with explicit truncation.""" return files.index_files(ctx.session) @_handler("search", ("queries",), ("queries",)) def search(ctx, args): """Search several phrasings for up to 20 titles and one-line descriptions, without bodies.""" return files.search_files(ctx.session, args["queries"]) @_handler("get", ("path",), ("path",)) def get(ctx, args): """Read one whole file, including a Database note's current shared text.""" return {"file": files.read_file(ctx.session, args["path"])} @_handler("links", ("database", "field"), ("database",)) def links(ctx, args): """Find up to 20 titles and one-line descriptions naming a database and optional field, without bodies.""" return files.linked_files(ctx, args["database"], args.get("field")) @_handler("propose", ("path", "body", "expectedVersion"), ("path", "body")) def propose(ctx, args): """Submit Markdown for its owner or declared approvers without replacing the approved file.""" return files.propose_file(ctx, args["path"], args["body"], expected_version=args.get("expectedVersion")) @_handler("create_wiki", ("path", "body"), ("path", "body")) def create_wiki(ctx, args): """Publish a new wiki/ page without a file proposal or owner approval; use propose for existing pages.""" return files.create_wiki_file(ctx, args["path"], args["body"]) @_handler("create_wiki", ("path", "body"), ("path", "body")) def _create_wiki_receipt_access(ctx, args): """Recheck access to the published wiki page without writing a usage record.""" files.read_file(ctx.session, args["path"], record_use=False) return True @_handler("propose", ("path", "body", "expectedVersion"), ("path", "body")) def _propose_receipt_access(ctx, args): """Recheck current file and source access without executing the proposal writer.""" files.read_file(ctx.session, args["path"], record_use=False) return True def _action(handler, properties=None, required=(), *, read=True, confirm=None, receipt_access=None): entry = {"read": read, "destructive": False, "confirm": not read if confirm is None else confirm, "schema": {"type": "object", "description": handler.__doc__, "properties": properties or {}, "required": list(required), "additionalProperties": False}, "handler": handler} if receipt_access is not None: entry["receipt_access"] = receipt_access return entry _PATH = {"type": "string", "maxLength": files.MAX_PATH, "description": "The relative .md path from index or search."} GROUP = { "name": "intelligence", "title": "Brain", "guide": "Read index for sections and your pins, then search with several phrasings. " "Both return metadata only and flag truncation. Use get for one whole file. " "Database notes are live files at database-notes/.md. " "Their text stays in the database's shared note. Agent edits require approval. " "Authenticated AI clients use links with an exact database key and optional field key. " "It matches keys named together in current front matter or body, including database.field, " "and returns bounded metadata with truncation. " "Propose previews a write for confirmation and then requests the file's approvals. " "Only approved text replaces the file. Pins use your intelligence.pins preference.\n\n" "### Brain files\n" "Write tenant facts, terms and preferences in Brain. Use a normalized relative .md path, " "such as company/team-guide.md, with at most 200 characters. " "Use ASCII letters, digits, dots, hyphens and underscores, with / between folders. " "No leading or trailing /, empty segments, . or .. segments, backslashes or spaces. " "The .md extension is case insensitive. " "Each file can be at most 128 KB (131072 UTF-8 bytes), including front matter and saved defaults.\n\n" "Start with YAML front matter between two --- lines, then write the Markdown body. " "Use unique text keys and no YAML aliases. " "Required keys: title is nonempty text, and section selects the file's category. " "Writable section keys: playbooks, agent-prompts, company-facts, dictionary-and-preferences, " "shared-results, agent-memory, wiki. Their displayed labels are also accepted. " "database-notes is reserved for notes maintained through their databases.\n\n" "owner is nonempty text, normally the owner's username, and defaults to the signed-in person. " "approvers is a list of nonempty names and defaults to []. " "Use usernames, person:username, role names or role:role names. " "Administrator and Administrators also select the admin role. " "approvals_needed is a positive whole number, default 1. " "Without named approvers it must be 1, and the owner or one Administrator approves. " "With named approvers, that many distinct eligible people must approve. " "description is optional text for search results.\n\n" "Brain example at company/team-guide.md. Replace your-username with your username.\n\n" " ---\n" " title: Team guide\n" " description: Shared team terms and facts\n" " section: company-facts\n" " owner: your-username\n" " approvers: []\n" " approvals_needed: 1\n" " reads: []\n" " tools: []\n" " ---\n" " # Team guide\n \n" " Record a fact, its source and when it was checked.\n\n" "### Skill files\n" "A skill is a Brain file with repeatable steps, usually in section playbooks or agent-prompts. " "Use the same path rules, front matter and size limit. " "tools is a list of unique, installed tool names, default []. " "Use group.action, such as intelligence.search or intelligence.get, or an available ungrouped tool name. " "Listing tools does not grant permission to use them. " "reads is a list of database keys, default []. Readers must have access to every listed database. " "Optional required_fields maps a database key in reads to a nonempty list of field keys. " "Discover database and field keys before listing them. " "Leave personal_scope to personal memory. It maps exactly person and tenant to lowercase, trimmed identifiers of at most 128 characters. " "person must equal owner, and only that person in that tenant can read it.\n\n" "Skill example at skills/review-brain.md. Replace both example usernames with people in your workspace.\n\n" " ---\n" " title: Review Brain facts\n" " description: Check a saved fact before using it\n" " section: playbooks\n" " owner: your-username\n" " approvers: [person:reviewer-username]\n" " approvals_needed: 1\n" " reads: []\n" " required_fields: {}\n" " tools: [intelligence.search, intelligence.get]\n" " ---\n" " # Review Brain facts\n \n" " 1. Search for the fact using several phrasings.\n" " 2. Get the matching file and check its source and date.\n" " 3. Report the supported fact or ask its owner to review it.\n\n" "### Editing files\n" "A person with read access may edit in place only as the owner or a named person approver " "(username or person:username). Role approvers, including Administrators, do not gain direct edit rights from their role. " "Other people and AIs propose changes to regular files for approval. " "Use intelligence.propose with path, body and the current expectedVersion from get. " "Confirmation submits the proposal. The published file's approval policy controls replacement. " "Changing owner or approvers in proposed front matter does not bypass that policy.\n\n" "### Tenant wiki\n" "Keep the tenant wiki in Brain's AutoWiki folder: wiki/log/.md for monthly activity, " "wiki/index/.md for indexes, wiki/purposes//.md for purpose records, " "and wiki/pages/.md for procedure pages. Replace placeholders with path-safe names. " "Use intelligence.create_wiki with path and body for a new page under wiki/. Use section: wiki. " "New wiki pages save without an owner approval or file proposal. " "The monthly log is generated by the system from confirmed activity, without AI prose. " "The system maintains wiki/log/ and wiki/index/. Do not write those paths. " "Editing an existing wiki page still needs owner or approver approval. " "Use intelligence.propose for edits. intelligence.propose still needs confirmation and approval. " "Wiki pages count toward the 2,000 Brain file limit. " "Send purpose with a build so its confirmed activity links to the purpose record and index.", "actions": { "index": _action(index), "search": _action(search, {"queries": {"type": "array", "minItems": 1, "maxItems": 20, "items": {"type": "string", "minLength": 1, "maxLength": 500}}}, ("queries",)), "get": _action(get, {"path": _PATH}, ("path",)), "links": _action(links, {"database": {"type": "string", "minLength": 1, "maxLength": 200}, "field": {"type": "string", "minLength": 1, "maxLength": 200}}, ("database",)), "propose": _action(propose, {"path": _PATH, "body": {"type": "string"}, "expectedVersion": {"type": "integer", "minimum": 0}}, ("path", "body"), read=False, receipt_access=_propose_receipt_access), "create_wiki": _action(create_wiki, {"path": {**_PATH, "description": "A new relative .md path under wiki/."}, "body": {"type": "string"}}, ("path", "body"), read=False, confirm=False, receipt_access=_create_wiki_receipt_access), }, }